Hypathesis

get_analysis_status

Check the processing status of an uploaded paper. Poll this tool after uploading a PDF until status is 'Ready' before calling get_variable_relationships. Args: file_id: The file_id returned by the /upload endpoint. authorization: Optional. API key as 'Bearer hk_...' or 'hk_...'. Returns: { "status": "Processing" | "Ready" | "Empty" | "Ineligible" | "Pending", "edges_count": int, "variables_count": int }

get_variable_relationships

Retrieve analyzed variable relationships for a completed paper. Only returns results when get_analysis_status reports status='Ready'. Without an API key (anonymous): returns the relationship list with source, target, and direction — but detailed reasoning is available only with an API key. Sign up at https://hypathesis.com to get one. Args: file_id: The file_id returned by the /upload endpoint. authorization: Optional. API key as 'Bearer hk_...' or 'hk_...'. Returns: Authenticated: full details (source, target, directed, reason per relationship; name, measure per variable). Anonymous: gated (source, target, directed per relationship; name per variable; sign_up_url for full access).

initiate_device_auth

Start a browser-based sign-in flow to get an API key for full access. Call this when you need detailed analysis results (reasoning, measurements) that require authentication. Returns a verification URL to show to the user. After the user signs in, poll check_device_auth with the returned user_code to get the API key. Returns: { "verification_url": str, "user_code": str, "expires_in": 600, "message": str }

No parameters.

check_device_auth

Check if the user has completed browser sign-in for a device auth request. Poll this after calling initiate_device_auth. Returns status 'pending' while waiting, or 'complete' with an api_key when the user has signed in. Use the returned api_key as the authorization parameter in other tools. Args: user_code: The user_code returned by initiate_device_auth. Returns: Pending: {"status": "pending"} Complete: {"status": "complete", "api_key": "hk_..."} Error: {"error": "..."}