docs(source-granola): update API key model and retry behavior

[devin-ai-integration]

Triggering Context

Run triggered by: Merged connector commit fe24599079e8df4686d82384a616c5b1eef78a73 on master (source-granola 0.2.12), delivered to this session by the autodoc workflow.

Relevant context: fix(source-granola): retry throttled and server-error responses with backoff (#84278)

Confidence impact: The trigger is a small, merged, single-connector change with an unambiguous scope, so the Triggering Context score is high.

Documentation Confidence Assessment

Overall Confidence: 4/5

Dimension	Score	Rationale
Code Comprehension of the Documented Surface	5/5	Manifest-only connector; every documented fact comes from manifest.yaml and metadata.yaml, with no custom components in the documented path.
API Documentation Quality	5/5	Granola publishes an OpenAPI document, an API changelog, rate limit figures, and a help-center guide to API keys and scopes.
Change Scope & Risk	4/5	46 lines changed across prerequisites, setup, streams, and performance — targeted corrections, no restructuring.
Existing Doc Maturity	3/5	The page was ~140 lines with solid structure but a key model that no longer matched the vendor.
Connector Sensitivity	5/5	Community connector, ql: 100 / sl: 100.
Triggering Context	5/5	Small merged PR with a clear, single-connector scope.
Inference Ratio	4/5	Nearly everything traces to the manifest or Granola's docs; the user-visible consequence of a 413 on detailed_notes is reasoned from the manifest plus the documented API response.

Adjustments based on code comprehension

• Declarative surface area: upward — all documented behavior (cursor, 30-day windows, include=transcript, API budget, error handler) is declared in manifest.yaml.
• Custom-component budget: upward — zero custom components; language:manifest-only in metadata.yaml.
• Independent corroboration: upward — rate limits, key scopes, and the 413 response appear both in Granola's OpenAPI document and its help-center pages.

What I Verified vs. What I Inferred

• Verified from code: max_retries: 5, WaitTimeFromHeader on Retry-After capped at 60s, ExponentialBackoffStrategy as the fallback (manifest.yaml base_requester.error_handler); the 25 requests / 5s HTTPAPIBudget; created_at cursor with step: P30D and no updated_at cursor; detailed_notes always sends include=transcript.
• Verified from API docs: personal API keys now carry Personal notes / Public notes access scopes rather than being split into "Personal" and "Enterprise" key types; workspace API keys are created by admins from Settings → Connectors → Workspace API keys, don't expire, and read public notes plus spaces with Allow Granola API access enabled; Enterprise admins gate member scopes in Settings → Workspace → General → API access for members; rate limits apply per user or per workspace depending on scope; Get Note returns 413 with TRANSCRIPT_TOO_LARGE when a transcript can't be returned inline.
• Inferred: that 413 responses cause the affected detailed_notes records to fail rather than be skipped — the manifest has no response filter for 413 and no fallback to /v1/notes/{note_id}/transcript, so the request is not handled gracefully, but I did not run a sync against an oversized transcript. Also inferred: that long meetings are the likeliest trigger for that limit.

Areas of Concern

• The connector spec's api_key description in manifest.yaml still describes the old "Enterprise API key" flow (Settings > API > Create new key) and the "Allow personal API keys" toggle. That's connector code, not docs, so I left it alone — it needs a separate connector PR to match this page and Granola's current UI.
• detailed_notes remains full refresh, so oversized-transcript notes affect every sync until the connector adopts the paged transcript endpoint.

---

What

Brings the Granola source docs back in line with Granola's current API and with connector behavior as of 0.2.12:

• The API key section described a "Personal API key (Beta)" versus "Enterprise API key" split that Granola no longer has. Keys are now personal or workspace-owned, and a personal key carries access scopes.
• The retry description predated the error handler added in fix(source-granola): retry throttled and server-error responses with backoff #84278.
• Two vendor links pointed at pages that now redirect to a single API page.

How

Corrections

• Rewrote Prerequisites, the key-generation steps, and "Data access by key type" around Granola's current model: personal keys with Personal notes / Public notes scopes, and admin-created workspace API keys. Replaced the stale personal-api and enterprise-api links with the current Granola API help-center page.
• Replaced "retries requests when a 429 Too Many Requests response is received" with the actual behavior from the new DefaultErrorHandler: up to 5 retries on 429 and 5xx, honoring Retry-After up to 60 seconds and otherwise backing off exponentially.
• Corrected the rate limit scoping sentence — limits apply per user or per workspace depending on the key's access scope, not per key type.

Additions

• Documented the 413 / TRANSCRIPT_TOO_LARGE case for detailed_notes, since the connector always requests the inline transcript and has no fallback to Granola's paged transcript endpoint.
• Noted that the created_at cursor means edits to already-synced notes aren't picked up incrementally.
• Added a pointer that a key limited to Public notes returns nothing until notes live in a workspace-visible folder — the most likely cause of an empty sync.

Review guide

• docs/integrations/sources/granola.md, Prerequisites and Setup guide: check the key types and menu paths against Granola's API help-center page.
• Same file, "Detailed notes": the 413 paragraph is the one claim with an inferred consequence.
• Same file, "Performance considerations": retry wording should match base_requester.error_handler in manifest.yaml.

User Impact

Users setting up the connector today were being sent to a key-creation flow that no longer exists, and had no way to know their sync retries server errors or can stall on very large transcripts. No connector behavior changes.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

---

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and third-party API documentation. Reviewers may merge, modify, or close this PR as they see fit.

---

Devin session

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-8zl4az7g8-airbyte-growth.vercel.app
Latest Commit:	3590ba2

Deployed with vercel-action

[octavia-bot-admin]

Auto-approved by auto-merge workflow.