# PageCompass

> Public book-recommendation API for AI assistants. PageCompass owns book ranking; clients provide the user's complete request and present the returned recommendations in order.

Production/API base: https://pagecompass.onrender.com

## Start here

Development guide: https://pagecompass.onrender.com/development
Agent docs: https://pagecompass.onrender.com/agent
Machine discovery: https://pagecompass.onrender.com/.well-known/pagecompass-agent.json
Shared library key guide: https://pagecompass.onrender.com/api/library/v1/bot-guide.txt
Shared library key OpenAPI: https://pagecompass.onrender.com/api/library/v1/openapi.json
All available agent capabilities: https://pagecompass.onrender.com/.well-known/pagecompass-capabilities.json
AI plugin: https://pagecompass.onrender.com/.well-known/ai-plugin.json
OpenAPI 3.1: https://pagecompass.onrender.com/agent/v1/openapi.json
Tool manifest: https://pagecompass.onrender.com/agent/v1/tools.json
Plugin manifest: https://pagecompass.onrender.com/agent/v1/manifest.json
MCP JSON-RPC: https://pagecompass.onrender.com/agent/mcp
Health: https://pagecompass.onrender.com/agent/v1/health

## Shared saved shelf (recommended)

Anonymous recommendations remain available. To use your existing shelf and save history, send Authorization: Bearer <PCL1- recovery key or PCBT1- approved assistant credential> on /agent/v1/recommend, /agent/v1/recommend/more and /agent/mcp. Verify /api/library/v1/me and the full expected account_id first. Stop on 401; never create a replacement shelf automatically.

Read saved catalog book status and paginated history with your approved device token. Saving statuses requires separately approved library:write, and automatic recommendation-history recording requires separately approved history:append. Recovery key owners retain their own actions. Follow the Library API guide and OpenAPI; this is separate from OAuth account writes.

## Human-approved reader accounts (SEPARATE authorization)

Recommendation endpoints return recommendations. Shared saved books and history use the Library API above. For private profile preferences, quality reports and human-approved lasting taste proposals, use the separate human-delegated OAuth account API:

Reader-agent discovery: https://pagecompass.onrender.com/.well-known/pagecompass-reader-agent.json
Reader-agent bot instructions: https://pagecompass.onrender.com/agent/account/v1/bot-guide.txt
Reader-agent OpenAPI 3.1: https://pagecompass.onrender.com/agent/account/v1/openapi.json
OAuth metadata: https://pagecompass.onrender.com/.well-known/oauth-authorization-server
Human-approved REST: https://pagecompass.onrender.com/agent/account/v1/*
Human-approved MCP: https://pagecompass.onrender.com/agent/account/mcp

NEVER use a public gateway key or the reader's PageCompass password for private account access. A vendor must support OAuth Code + PKCE and have an operator-verified registered client_id/redirect_uri. The HUMAN must approve scopes at PageCompass login. Check discovery first: the client allowlist may be empty, and no Muse/Grok vendor support is assumed.

Ask only for necessary scopes: profile:read, library:read, quality:report, profile:suggest. Recommend profile:suggest instead of direct profile writes; OAuth profile:write and OAuth library:write are disabled by default; that does not disable shared Library API saved-book writes. All quality reports are evidence-only, not automatic catalog or ranking edits.

The public recommendation MCP at /agent/mcp and private reader MCP at /agent/account/mcp are DIFFERENT tools, credentials, and transports.


Anonymous access is available when discovery reports auth.mode = "anonymous" or "optional".

## First recommendation

POST https://pagecompass.onrender.com/agent/v1/recommend
Content-Type: application/json

{"query":"I want a practical leadership book with real workplace examples. No academic textbook."}

Omit session_id on the first turn. Save the returned session_id (agent-<UUID>).

## Continue the same ask

If the user wants another slate under the same constraints:

POST https://pagecompass.onrender.com/agent/v1/recommend/more

{"query":"More options under my previous request.","session_id":"agent-<UUID>","exclude_book_ids":["<book-id-already-shown>"]}

The server reuses the ORIGINAL query and resolved intent for /more; the query field is a continuation label, not a new interpretation. If SESSION_CONTEXT_MISSING occurs (e.g. after process restart), submit the full original query to /recommend with the same session_id.

## Refine or change constraints

Call POST /agent/v1/recommend again with the same session_id and the complete updated query.

{"query":"Keep it practical, under about 350 pages, and no academic textbooks.","session_id":"agent-<UUID>"}

Preserve constraint-bearing words verbatim: no, not, only, avoid, without, must, under, beginner, advanced.

## Feedback

Optional feedback can accompany recommend/more:

{"on_primary_id":"<book-id>","outcome":"reject","reasons":["too_long"],"note":"I want something shorter."}

outcome: reject | accept | keep
reasons: too_dark | too_slow | not_my_vibe | wrong_genre | wrong_subgenre | too_light_novel | not_hard_sf | too_long | too_short

## Response handling

- recommendation.primary is PageCompass's first choice.
- recommendation.alternatives are ordered by PageCompass. Do not re-rank them.
- Keep session_id for subsequent turns.
- Send exclude_book_ids to avoid repeats.
- If constraint_check.failed is non-empty, do not claim that title satisfies the failed hard constraint.
- If recommendation.zero_result is true, show refinement_chips and constraint_blockers. Do not silently relax hard constraints.
- Follow next_actions when useful.
- Stop calling when the user accepts a recommendation.
- Allow up to 90 seconds for recommendation requests.
- A real spine failure is HTTP 503, never a 200 with prose. REST body: {"error":{"code":"spine_timeout","retryable":true}}. Honor Retry-After.
- MCP keeps JSON-RPC. error.retryable is true, and the same code string is error.data.code.
- An honest miss stays HTTP 200 with recommendation.zero_result true.
- CORS on /agent/* is Access-Control-Allow-Origin: * by default. Cookies are not accepted. AGENT_CORS=same-origin removes the wildcard.

## MCP

POST https://pagecompass.onrender.com/agent/mcp with JSON-RPC 2.0.
Initialize, call tools/list, then tools/call.
Tools: pagecompass_recommend, pagecompass_more.
Use the same input fields and session rules as REST.

## Scope

Public recommendation endpoints support anonymous discovery and optional authenticated shelf context and recommendation-history recording. Read and save catalog book statuses only through /api/library/v1 with a verified existing Library credential. The public recommendation API never exposes purchase, checkout, administration, ingestion, uploaded-book content or account editing. A library-scoped assistant cannot approve new assistant connections or create accounts automatically.