Show HN: Granola API Reverse Engineering

Reverse-engineered documentation of the Granola API, including authentication flow and endpoints.

This work builds upon the initial reverse engineering research by Joseph Thacker:

• Reverse Engineering Granola Notes

Granola uses WorkOS for authentication with refresh token rotation.

Authentication Flow:

1. Initial Authentication

   • Requires refresh_token from WorkOS authentication flow
   • Requires client_id to identify the application to WorkOS

2. Access Token Exchange

   • Refresh token is exchanged for short-lived access_token via WorkOS /user_management/authenticate endpoint
   • Request: client_id, grant_type: "refresh_token", current refresh_token
   • Response: new access_token, rotated refresh_token, expires_in (3600 seconds)

3. Token Rotation (IMPORTANT)

   • Refresh tokens CANNOT be reused - each token is valid for ONE use only
   • Each exchange automatically invalidates the old refresh token and issues a new one
   • You MUST save and use the new refresh token from each response for the next request
   • Attempting to reuse an old refresh token will result in authentication failure
   • This rotation mechanism prevents token replay attacks
   • Access tokens expire after 1 hour

• main.py - Document fetching and conversion logic (includes workspace, folder, and batch fetching)
• token_manager.py - OAuth token management and refresh
• list_workspaces.py - List all available workspaces (organizations)
• list_folders.py - List all document lists (folders)
• filter_by_workspace.py - Filter and organize documents by workspace
• filter_by_folder.py - Filter and organize documents by folder
• GETTING_REFRESH_TOKEN.md - Method to extract tokens from Granola app

Exchanges a refresh token for a new access token using WorkOS authentication.

Endpoint: POST https://api.workos.com/user_management/authenticate

Request Body:

Response:

IMPORTANT - Refresh Token Rotation:

• The refresh_token in the response is a NEW token that replaces the old one
• The old refresh token is immediately invalidated and CANNOT be reused
• You MUST save this new refresh token and use it for the next authentication request
• Failure to update the refresh token will cause subsequent authentication attempts to fail
• This is a security feature called "refresh token rotation" that prevents token replay attacks

Retrieves a paginated list of user's Granola documents.

Endpoint: POST https://api.granola.ai/v2/get-documents

Headers:

Request Body:

Response:

Limitations:

• Does NOT return shared documents - only returns documents owned by the user
• For fetching documents from folders (which may contain shared documents), use get-documents-batch instead

Retrieves the transcript (audio recording utterances) for a specific document.

Endpoint: POST https://api.granola.ai/v1/get-document-transcript

Headers:

Request Body:

Response:

Notes:

• Returns 404 if document has no associated transcript
• Transcripts are generated from meeting recordings

Retrieves all workspaces (organizations) accessible to the user.

Endpoint: POST https://api.granola.ai/v1/get-workspaces

Headers:

Request Body:

Response:

Notes:

• Workspaces are organizations/teams
• Each document belongs to a workspace via the workspace_id field

Retrieves all document lists (folders) accessible to the user.

Endpoints:

• POST https://api.granola.ai/v2/get-document-lists (preferred)
• POST https://api.granola.ai/v1/get-document-lists (fallback)

Headers:

Request Body:

Response:

Notes:

• Document lists are the folder system in Granola
• A document can belong to multiple lists
• Lists are workspace-specific
• Try v2 endpoint first, fallback to v1 if not available
• Response format differs slightly between v1 and v2

Fetch multiple documents by their IDs. This is the most reliable way to fetch documents from folders, especially shared documents.

Endpoint: POST https://api.granola.ai/v1/get-documents-batch

Headers:

Request Body:

Response:

Notes:

• IMPORTANT: The get-documents endpoint does NOT return shared documents. Use this batch endpoint to fetch shared documents.
• Recommended workflow for folders:
  1. Use get-document-lists to get folder contents (returns document IDs)
  2. Use get-documents-batch to fetch the actual documents (including shared ones)
• Batch size limit is typically 100 documents per request
• This endpoint works with both owned and shared documents
• Response may use either "documents" or "docs" field name

Documents are converted from ProseMirror to Markdown with frontmatter metadata:

Each document is saved with a metadata.json file containing:

The main script now automatically fetches workspace information along with documents:

This will:

1. Fetch all workspaces and save to workspaces.json
2. Fetch all document lists (folders) and save to document_lists.json
3. Fetch all documents with workspace and folder information
4. Save each document with metadata including workspace_id, workspace_name, and folders

View all available workspaces:

Output:

View all document lists (folders):

Output:

List all workspaces with document counts:

Filter by workspace ID:

Filter by workspace name:

View all documents grouped by workspace:

List all folders with document counts:

Filter by folder ID:

Filter by folder name:

Show documents not in any folder:

View all documents grouped by folder:

After running main.py, documents are organized as follows:

• Workspaces: Organizations or teams that contain documents and folders
• Document Lists (Folders): Collections of documents within a workspace
• Documents: Individual notes/meetings with transcripts and AI-generated summaries
• A document belongs to one workspace but can be in multiple folders
• Documents can exist without being in any folder