Granola Meeting Notes API

intent

Read-only access to meeting notes, summaries, transcripts, and attendee info from the official Granola REST API. use this when the user asks "what did we talk about in [meeting]", "who attended [meeting]", needs to find meetings with a specific person, wants to retrieve action items or discussion points, or explicitly mentions "Granola". the skill fetches notes that have completed AI summarization and transcription only. network requests go HTTPS-only to public-api.granola.ai.

inputs

external connection: granola api

• endpoint: https://public-api.granola.ai/v1
• auth method: bearer token in Authorization header
• env var: GRANOLA_API_KEY (required, business or enterprise plan)
• scopes: read-only access to notes, summaries, transcripts, attendee lists
• rate limits: 25 req/5 sec burst, 5 req/sec sustained (300/min). on 429, back off and retry

local binaries required

• curl (https requests)
• jq (json parsing)

input parameters (user intent)

• search window: days back (default 7)
• note id: for single-note fetches (pattern not_[a-zA-Z0-9]{14})
• attendee name: to filter meetings by participant
• include transcript: boolean (only request when user needs verbatim content)

procedure

1. verify api key

   • input: check if GRANOLA_API_KEY env var is set
   • output: confirm key exists or fail with setup instructions
   • edge case: if unset, return error pointing to README.md

2. list recent notes

   • input: desired lookback window (e.g., 7 days)
   • call: GET /v1/notes?page_size=20&created_after=<iso-timestamp>&updated_after=<iso-timestamp>
   • output: json array of note objects with id, title, owner, created_at, updated_at
   • edge case: if hasMore=true, use cursor for pagination

3. filter by title or owner (client-side)

   • input: list of notes from step 2, user's search terms
   • process: grep/jq-filter notes by title or owner name
   • output: matching note ids and metadata
   • edge case: if no matches, report "no meetings found in window"

4. fetch single note with details

   • input: note id from step 3 (or user-provided id)
   • call: GET /v1/notes/{note_id}?include=transcript (if transcript needed)
   • output: full note object with summary_text, summary_markdown, attendees, calendar_event, transcript array
   • edge case: if 404, note may still be processing; suggest retrying in a few minutes

5. extract and present summary

   • input: note object from step 4
   • process: use summary_markdown if available, fallback to summary_text
   • output: formatted summary string
   • edge case: if summary fields null, note processing not complete yet

6. extract attendees (if requested)

   • input: note object from step 4
   • process: map attendees array to { name, email } tuples
   • output: list of participants
   • edge case: if attendees array empty, no explicit attendee list (calendar invitees may differ)

7. extract transcript segments (if requested)

   • input: note object from step 4 with include=transcript
   • process: iterate transcript array, format as "<speaker_source>: <text> [<start_time>]"
   • output: plaintext transcript or json array
   • edge case: speaker.source is either "microphone" (local user) or "speaker" (others); timestamp fields may be null

8. search for meetings with specific person

   • input: attendee name (partial match ok)
   • process: list all recent notes (steps 2-3), then fetch each (step 4) and filter by attendees array
   • output: note ids and titles where person attended
   • edge case: if no match after 30 days, extend window or try exact email

decision points

if api key missing or invalid (401):

• halt and direct user to README.md for setup instructions
• do not retry with empty key

if note returns 404:

• check: is note id malformed? if so, report invalid id format
• else: note may still be processing (ai summary not yet complete) or user lacks access; suggest retrying in a few minutes

if rate limit hit (429):

• back off exponentially (1-5 seconds)
• retry up to 2 times
• if still 429, report quota exceeded and suggest trying again later

if user requests transcript vs. summary:

• if "full transcript" or "verbatim" or "word-for-word", include ?include=transcript in request
• else: omit transcript param (smaller response, faster)

if pagination needed (hasMore=true):

• if user asks "show me more", pass cursor from previous response
• else: return first page only

if search by attendee name:

• if exact email provided, filter client-side on attendees[].email
• if name substring provided, case-insensitive regex match on attendees[].name
• if no match in recent 30 days, extend created_after window or fail gracefully

if summary fields null:

• note processing not yet complete; do not return empty summary
• advise user to retry in a few minutes

output contract

on success (list notes):

{
  "notes": [
    {
      "id": "not_1d3tmYTlCICgjy",
      "title": "Weekly sync with engineering",
      "owner": { "name": "Jane Smith", "email": "jane@example.com" },
      "created_at": "2026-04-14T15:30:00Z",
      "updated_at": "2026-04-14T16:45:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJjcmVkZW50aWFsfQ=="
}

on success (get single note with summary):

{
  "id": "not_1d3tmYTlCICgjy",
  "title": "Weekly sync with engineering",
  "owner": { "name": "Jane Smith", "email": "jane@example.com" },
  "created_at": "2026-04-14T15:30:00Z",
  "updated_at": "2026-04-14T16:45:00Z",
  "attendees": [
    { "name": "Jane Smith", "email": "jane@example.com" },
    { "name": "Bob Chen", "email": "bob@example.com" }
  ],
  "summary_text": "Discussed sprint progress and blockers. Decided to push the release to next week.",
  "summary_markdown": "## Weekly Sync\n\n- Sprint progress reviewed\n- Release pushed to next week"
}

on success (get single note with transcript):

{
  "id": "not_1d3tmYTlCICgjy",
  "title": "Weekly sync with engineering",
  "summary_text": "...",
  "transcript": [
    {
      "speaker": { "source": "microphone" },
      "text": "Let's start with the sprint update.",
      "start_time": "2026-04-14T15:30:12Z",
      "end_time": "2026-04-14T15:30:18Z"
    },
    {
      "speaker": { "source": "speaker" },
      "text": "We're about two days behind on the auth module.",
      "start_time": "2026-04-14T15:30:20Z",
      "end_time": "2026-04-14T15:30:28Z"
    }
  ]
}

on error (401):

ERROR: Granola API key invalid or missing.
Set GRANOLA_API_KEY environment variable. See README.md for setup.

on error (404):

ERROR: Note not_XXXXXXXXXXXXXX not found. 
Note may still be processing. Retry in a few minutes. Or ID may be incorrect.

on error (429):

ERROR: Rate limit exceeded. Waiting 3 seconds before retry...

on error (500):

ERROR: Granola server error. Retry after a brief delay.

outcome signal

• user sees formatted summary text (plain or markdown) from requested meeting
• user sees attendee list with names and emails
• user sees full transcript with speaker turns and timestamps (if requested)
• user sees meeting title, created date, and owner
• user can page through multiple meetings without hitting rate limits
• on failure, error message clearly states root cause (bad key, not found, rate limit, server error) and next step

---

security and data handling

this skill is read-only. it cannot create, edit, or delete any data in granola.

network access: https requests only to public-api.granola.ai. no other domains contacted.

credential handling: api key read from GRANOLA_API_KEY environment variable, passed only in the http Authorization header. the skill itself does not write the key to disk at runtime. follow established best practices for secret management on your host.

no external code execution: uses only curl and jq. no downloads, no scripts, no binaries.

---

authentication

-H "Authorization: Bearer $GRANOLA_API_KEY"

if you get a 401 error, the key is missing or invalid. check that GRANOLA_API_KEY is set and points to a valid business or enterprise granola api key.

---

base url

https://public-api.granola.ai/v1

---

rate limits

burst: 25 requests per 5 seconds. sustained: 5 req/sec (300/min). on 429, back off a few seconds and retry. after 2 retries, fail gracefully and suggest user retry later.

---

important behaviors

• only notes with a completed ai summary and transcript are returned. notes still processing or never summarized are excluded (list omits them; get returns 404).
• note ids follow the pattern not_[a-zA-Z0-9]{14} (e.g., not_1d3tmYTlCICgjy).
• the api has no search endpoint. to find meetings by topic, list recent notes and scan titles/summaries client-side.

---

endpoints

1. list notes

GET /v1/notes

query parameters:

parameter	type	default	description
page_size	integer (1-30)	10	max notes per page
created_after	iso 8601 date/datetime	-	notes created after this date
created_before	iso 8601 date/datetime	-	notes created before this date
updated_after	iso 8601 date/datetime	-	notes updated after this date
cursor	string	-	pagination cursor from previous response

example:

curl -s "https://public-api.granola.ai/v1/notes?page_size=20&created_after=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Authorization: Bearer $GRANOLA_API_KEY" | jq .

on macOS, replace -d '7 days ago' with -v-7d.

response:

{
  "notes": [
    {
      "id": "not_1d3tmYTlCICgjy",
      "object": "note",
      "title": "Weekly sync with engineering",
      "owner": { "name": "Jane Smith", "email": "jane@example.com" },
      "created_at": "2026-04-14T15:30:00Z",
      "updated_at": "2026-04-14T16:45:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJjcmVkZW50aWFsfQ=="
}

when hasMore is true, pass the cursor value to fetch the next page.

---

2. get a single note

GET /v1/notes/{note_id}

path parameter: note_id (required, pattern: not_[a-zA-Z0-9]{14})

query parameter:

parameter	type	description
include	"transcript"	include the full transcript in response

example:

curl -s "https://public-api.granola.ai/v1/notes/not_1d3tmYTlCICgjy?include=transcript" \
  -H "Authorization: Bearer $GRANOLA_API_KEY" | jq .

response:

{
  "id": "not_1d3tmYTlCICgjy",
  "object": "note",
  "title": "Weekly sync with engineering",
  "owner": { "name": "Jane Smith", "email": "jane@example.com" },
  "created_at": "2026-04-14T15:30:00Z",
  "updated_at": "2026-04-14T16:45:00Z",
  "calendar_event": {
    "event_title": "Weekly sync with engineering",
    "invitees": [{ "email": "bob@example.com" }],
    "organiser": "jane@example.com",
    "scheduled_start_time": "2026-04-14T15:30:00Z",
    "scheduled_end_time": "2026-04-14T16:30:00Z"
  },
  "attendees": [
    { "name": "Jane Smith", "email": "jane@example.com" },
    { "name": "Bob Chen", "email": "bob@example.com" }
  ],
  "folder_membership": [
    { "id": "fol_4y6LduVdwSKC27", "object": "folder", "name": "Engineering" }
  ],
  "summary_text": "Discussed sprint progress and blockers. Decided to push the release to next week.",
  "summary_markdown": "## Weekly Sync\n\n- Sprint progress reviewed\n- Release pushed to next week",
  "transcript": [
    {
      "speaker": { "source": "microphone" },
      "text": "Let's start with the sprint update.",
      "start_time": "2026-04-14T15:30:12Z",
      "end_time": "2026-04-14T15:30:18Z"
    },
    {
      "speaker": { "source": "speaker" },
      "text": "We're about two days behind on the auth module.",
      "start_time": "2026-04-14T15:30:20Z",
      "end_time": "2026-04-14T15:30:28Z"
    }
  ]
}

key response fields:

field	description
summary_text	plain-text ai summary
summary_markdown	markdown-formatted ai summary (may be null)
attendees	array of { name, email } for meeting participants
calendar_event	calendar metadata: title, invitees, organiser, scheduled times
folder_membership	folders the note belongs to
transcript	speaker segments with text, start_time, end_time

transcript speaker sources: "microphone" = local user, "speaker" = other participants via meeting audio.

---

error handling

status	meaning	action
401	invalid or missing api key	check GRANOLA_API_KEY is set and valid
404	note not found	note may still be processing, or id is wrong
429	rate limit exceeded	wait a few seconds and retry
500	server error	retry after a brief delay

---

workflow recipes

find meetings from the last N days

DAYS=7
curl -s "https://public-api.granola.ai/v1/notes?page_size=30&created_after=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ