{"name":"PageCompass Agent Gateway","api_version":"v1","capability_registry":"https://pagecompass.onrender.com/.well-known/pagecompass-capabilities.json","description":"Plugin/Skill/MCP-friendly access to the existing PageCompass recommendation system. The gateway is an adapter; ranking and scoring remain owned by the canonical website recommendation spine.","auth":{"mode":"anonymous","anonymous_available":true,"bearer_supported":true,"optional_library_bearer":true,"library_bot_guide":"https://pagecompass.onrender.com/api/library/v1/bot-guide.txt","library_openapi":"https://pagecompass.onrender.com/api/library/v1/openapi.json","recommendation_bot_guide":"https://pagecompass.onrender.com/agent/v1/bot-guide.txt","on_invalid_credential":"stop_and_reconnect_no_anonymous_fallback","library_bearer_supported":true,"library_key_guide":"https://pagecompass.onrender.com/api/library/v1/bot-guide.txt","note":"Anonymous recommendations remain available. Send Authorization: Bearer <PCL1 recovery key or PCBT1 approved assistant token> for your existing shelf context and saved history. Invalid library credentials never fall back to anonymous. Shared saved-book writes use /api/library/v1; OAuth account write flags are a separate API."},"operations":[{"name":"pagecompass_recommend","description":"Recommend books only. Send the complete request, preserving only, no, avoid and without. Authenticated calls may read the connected saved shelf and record recommendation history; these tools do not purchase books, change accounts, or write saved-book statuses. PageCompass ranks the slate: present recommendation.primary first. Retryable upstream failures are HTTP 503 with error.retryable true and Retry-After; honest misses are zero_result."},{"name":"pagecompass_more","description":"More book recommendations under the same original request. Send the prior session_id and exclude_book_ids; use pagecompass_recommend when constraints change. Authenticated calls may read the connected saved shelf and record recommendation history; no purchases, account changes, or saved-book status writes. A retryable upstream failure is HTTP 503 with error.retryable true and Retry-After. Keep the returned ranking."}],"safety":{"recommendation_only":true,"purchases":false,"account_edits":false,"admin_writes":false,"library_writes":false},"consistency":{"canonical_pipeline":["POST /api/interpret","POST /api/recommend-tiered"],"gateway_ranking_logic":false},"discovery":{"development":"https://pagecompass.onrender.com/development","agent_docs":"https://pagecompass.onrender.com/agent","well_known":"https://pagecompass.onrender.com/.well-known/pagecompass-agent.json","capability_registry":"https://pagecompass.onrender.com/.well-known/pagecompass-capabilities.json","ai_plugin":"https://pagecompass.onrender.com/.well-known/ai-plugin.json","llms":"https://pagecompass.onrender.com/llms.txt","bot_guide":"https://pagecompass.onrender.com/agent/v1/bot-guide.txt","capabilities":"https://pagecompass.onrender.com/.well-known/pagecompass-capabilities.json","reader_account_discovery":"https://pagecompass.onrender.com/.well-known/pagecompass-reader-agent.json","reader_account_bot_guide":"https://pagecompass.onrender.com/agent/account/v1/bot-guide.txt","openapi":"https://pagecompass.onrender.com/agent/v1/openapi.json","tools":"https://pagecompass.onrender.com/agent/v1/tools.json","manifest":"https://pagecompass.onrender.com/agent/v1/manifest.json","health":"https://pagecompass.onrender.com/agent/v1/health","mcp":"https://pagecompass.onrender.com/agent/mcp"},"human_delegation":{"discovery":"https://pagecompass.onrender.com/.well-known/pagecompass-reader-agent.json","note":"Separate OAuth/PKCE human-approved API for profiles, saved lists and report-only quality/taste signals. Public gateway keys and cookies cannot access it.","human_approval_required":true,"not_part_of_public_recommendation_mcp":true},"quick_start":{"first_turn":{"method":"POST","path":"/agent/v1/recommend","body":{"query":"I want a fast science-fiction novel, no horror"}},"continue_same_request":{"method":"POST","path":"/agent/v1/recommend/more","carry":["session_id","exclude_book_ids"]},"refine_or_change_constraints":{"method":"POST","path":"/agent/v1/recommend","carry":["session_id"],"note":"Send the complete updated query; do not silently remove hard constraints."},"timeout_ms":90000,"retry":"Honor Retry-After for retryable 429/503/504 responses."},"bot_rules":["Preserve the user's exact constraint-bearing wording.","Treat recommendation.primary as the first PageCompass choice and preserve alternatives order.","If constraint_check.failed is non-empty, do not present that title as satisfying the failed constraint.","If zero_result is true, show refinement_chips/constraint_blockers instead of weakening constraints silently.","Stop calling when the user accepts a recommendation."],"mcp":{"protocol_version":"2026-07-28","transport":"stateless-http-json-rpc","endpoint":"https://pagecompass.onrender.com/agent/mcp","tools":["pagecompass_recommend","pagecompass_more"]}}