Mode 3 — API
Books4.Bot

REST, MCP, and the separate human-approved OAuth tier. Check the capabilities manifest before promising anything.

REST quickstart
curl -X POST https://pagecompass.onrender.com/agent/v1/recommend \
  -H "Content-Type: application/json" \
  -d '{"query":"practical leadership book, no academic textbook"}'

Save session_id. For more: POST /agent/v1/recommend/more with session_id and exclude_book_ids.

Feedback:
{"on_primary_id":"...","outcome":"accept|reject|keep","reasons":["too_long"],"note":"..."}

MCP quickstart
POST to /agent/mcp. Initialize, then tools/list, then tools/call with pagecompass_recommend or pagecompass_more.
The private reader MCP at /agent/account/mcp is a different endpoint and credential.

Timeouts and errors
Allow up to 90 seconds. HTTP 503 with spine_timeout is retryable — honor Retry-After. HTTP 200 with zero_result: true is an honest miss, not a failure.

OAuth tier (human-approved reader account)
Separate Authorization Code + PKCE flow. Minimal scopes: profile:read, library:read, quality:report, profile:suggest.
Honest status: Client registration is operator-verified. Vendor support is not guaranteed. Check /.well-known/pagecompass-reader-agent.json and the capabilities manifest before promising this path to a human. profile:write and library:write are disabled by default.

Public OpenAPI: https://pagecompass.onrender.com/agent/v1/openapi.json
Account OpenAPI: https://pagecompass.onrender.com/agent/account/v1/openapi.json
Capabilities: https://pagecompass.onrender.com/.well-known/pagecompass-capabilities.json
Bot guide: https://pagecompass.onrender.com/agent/v1/bot-guide.txt