{"name":"PageCompass Human-Delegated Reader API","version":"1.0.0","description":"Human-approved profile and reading lists, plus evidence-only catalog/recommendation/site reports and human-reviewed taste suggestions.","available_without_auth":false,"registration":{"mode":"restricted_dynamic_and_manual","dynamic_client_registration":true,"registration_endpoint":"https://pagecompass.onrender.com/oauth/register","any_registered_clients":true,"note":"Apps with callbacks on explicitly configured provider hosts may register through the OAuth registration endpoint. Readers still sign in and grant scopes themselves. Other callback hosts are refused."},"auth":{"mode":"oauth2_authorization_code_pkce_s256","client_authentication":"none","browser_login_and_consent":"human_only_on_pagecompass","issuer":"https://pagecompass.onrender.com","resource":"https://pagecompass.onrender.com/agent/account","authorization_server_metadata":"https://pagecompass.onrender.com/.well-known/oauth-authorization-server","protected_resource_metadata":"https://pagecompass.onrender.com/.well-known/oauth-protected-resource/agent/account","authorize":"https://pagecompass.onrender.com/oauth/authorize","token":"https://pagecompass.onrender.com/oauth/token","revoke":"https://pagecompass.onrender.com/oauth/revoke","code_ttl_seconds":90,"access_token_ttl_seconds":900,"grant_ttl_days":30,"refresh_token_rotation":true},"library_device_connection":{"independent_of_oauth_client_registration":true,"availability":"https://pagecompass.onrender.com/api/library/v1/availability","bot_guide":"https://pagecompass.onrender.com/api/library/v1/bot-guide.txt","openapi":"https://pagecompass.onrender.com/api/library/v1/openapi.json","reader_approval_page":"https://pagecompass.onrender.com/library/connect","assistant_request_endpoint":"https://pagecompass.onrender.com/api/library/v1/device-authorizations","default_scopes":["library:read","history:read"],"requires_human_code_match":true,"note":"Reader must supply their full existing account_id. Assistant verifies /me and ACKs; OAuth client registration and password are NOT required. Device grants never imply OAuth profile access."},"interfaces":{"rest_openapi":"https://pagecompass.onrender.com/agent/account/v1/openapi.json","rest_base":"https://pagecompass.onrender.com/agent/account/v1","mcp_endpoint":"https://pagecompass.onrender.com/agent/account/mcp","mcp_protocol_version":"2025-06-18","public_recommendation_mcp":"https://pagecompass.onrender.com/agent/mcp","public_recommendation_openapi":"https://pagecompass.onrender.com/agent/v1/openapi.json","human_connections":"https://pagecompass.onrender.com/account","human_taste_approval":"https://pagecompass.onrender.com/account","docs":"https://pagecompass.onrender.com/development"},"permissions":{"scopes_supported":["profile:read","profile:write","library:read","library:write","quality:report","profile:suggest"],"scope_descriptions":{"profile:read":"View your reading preferences and profile name","profile:write":"Update your favorite genres, authors, and reading moods","library:read":"View your saved books and reading status","library:write":"Add books to your lists or change their reading status","quality:report":"Report book, recommendation and site defects for review","profile:suggest":"Suggest reading preferences for your approval (never silently changes tastes)"},"recommended_minimal_scopes":["profile:read","library:read","quality:report","profile:suggest"],"direct_profile_writes_enabled":true,"library_status_writes_enabled":true},"reader_preferences":{"supported_dislike_codes":["sprawling_cast","tedious_pacing","needlessly_confusing","dense_prose","romance_heavy","graphic_violence","bleak_ending"],"source":"reader_approved_reading_setup","draft_tool":"pagecompass_propose_reading_setup","drafting_scope":"profile:suggest","ranking_mode":"shadow_by_default","note":"Only human-confirmed dislikes are eligible; ranking promotion is separately protected."},"recommended_actions":["Use the public /agent/v1/recommend or /agent/mcp for book discovery; keep the returned session_id and book IDs.","Use delegated OAuth only for data that belongs to the human (profile, lists, reports, suggestions).","After the reader approves scopes, call authenticated MCP tools/list: it returns only tools actually granted and enabled.","For a missing cover or wrong book metadata, submit a catalog quality report (not a catalog edit).","For an off-target recommendation, report the exact book ID, stated constraint and reason; treat it as an unverified observation.","For inferred favorite genres/authors/moods, submit a proposal; only the human may approve a profile change.","For soft or hard dislikes, send a reader-reviewable reading setup draft; never overwrite existing favorites to add a dislike.","Never reinterpret or remove a hard constraint, claim verified impressions from a self-reported session, or alter rankings."],"prohibitions":["password_or_mfa_access","account_takeover","billing_or_purchase","private_epub_pdf_audio_access","catalog_write","ranking_write","chiropractor_promotion","admin_access","production_deployment"]}