# Pocket Docs Pocket is a precision-milled aluminum device designed to capture your thoughts, meetings, and conversations, turning them into structured insights and action items automatically. ## How it Works [#how-it-works] Pocket lives on the back of your phone. Use the **physical slider** to switch modes and the **side button** to start capturing. 1. **Capture**: Press once to record. Pocket's ultra-sensitive mics catch every detail. 2. **Sync**: Open the app to sync your recordings via Wi-Fi or Bluetooth. 3. **Insight**: Our AI generates perfectly formatted summaries, action items, and mind maps. 4. **Execute**: Add action items to your calendar with a single tap. ## Get Started [#get-started] ## Key Features [#key-features] ## Support and Community [#support-and-community] ## Popular questions [#popular-questions] ### How do I pair my Pocket device? [#how-do-i-pair-my-pocket-device] Start with [Pairing your Pocket](/docs/getting-started/pairing). Turn Pocket on, wait for the blinking blue light, open the Pocket app, allow Bluetooth permissions, and select your device from the pairing screen. ### How do I sync Pocket recordings? [#how-do-i-sync-pocket-recordings] Pocket can sync through the app, Wi-Fi, Bluetooth, or USB-C with [Pocket Web Sync](/docs/features/device/pocket-web-sync). Use Web Sync for large recordings or when you want the fastest import on desktop. ### Can Pocket connect to Claude, Cursor, or other AI tools? [#can-pocket-connect-to-claude-cursor-or-other-ai-tools] Yes. Use the [Pocket MCP Server](/docs/mcp) to connect your recordings to MCP-compatible tools including Claude, Cursor, Littlebird, and other AI assistants. ### Does Pocket have an API? [#does-pocket-have-an-api] Yes. The [Pocket Public API](/docs/api) supports recordings, transcripts, summaries, semantic search, tags, users, and webhooks for custom integrations. # Pocket MCP Server We’re excited to announce **Pocket MCP Server** – a new way to connect your Pocket recordings directly to AI assistants like Claude, Cursor, Littlebird, and other MCP-compatible tools. ## What is MCP? [#what-is-mcp] Model Context Protocol (MCP) is an open standard that lets AI assistants securely access your data. With Pocket’s MCP server, you can now ask AI questions about your recordings, search across all your transcripts, and get insights – all within your favorite AI tools. ### What can you do with it? [#what-can-you-do-with-it] * "What did I discuss in my meetings last week?" * "Find all recordings where I talked about the product launch" * "Summarize my conversation from yesterday" * "Mark that follow-up action as done" — updates flow back into Pocket * Search across all your recordings without leaving your workflow ## Setup Instructions [#setup-instructions] Pocket MCP supports both **OAuth** (recommended) and **API keys**. OAuth is the simplest option for most clients; API keys are available for clients that only support static headers. ### Option 1: OAuth (recommended) [#option-1-oauth-recommended] OAuth is the fastest path. Add Pocket as a remote MCP server and follow the OAuth login prompt to authorize access. **MCP server URL** ``` https://public.heypocketai.com/mcp ``` ### Option 2: API key (manual headers) [#option-2-api-key-manual-headers] Get your API key from **Pocket Settings → Developer → API Keys**. Your key starts with `pk_...`. Pocket MCP accepts either header format: * `Authorization: Bearer pk_...` (recommended), or * `Authorization: ApiKey pk_...` If your client uses `mcp-remote`, make sure the `Authorization` header is forwarded with the `--header` argument. **Note:** Some MCP clients (including Claude Desktop and Cursor) can mangle command arguments that contain spaces. The examples below use `Authorization:${AUTH_HEADER}` with a separate `AUTH_HEADER` environment variable to avoid this issue. ### Cursor [#cursor] **OAuth install (recommended):** Install in Cursor **Manual setup with API key:** 1. Open Cursor Settings (`Cmd/Ctrl + ,`) 2. Search for "MCP" or go to **Features → MCP Servers** 3. Click **Add Server** and enter: ```json { "pocket": { "command": "npx", "args": [ "-y", "mcp-remote", "https://public.heypocketai.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer pk_your_api_key_here" } } } ``` 4. Restart Cursor. ### Claude Desktop [#claude-desktop] **OAuth (recommended):** 1. Open Claude Desktop → **Settings → Connectors** 2. Click **Add custom connector** 3. Paste the MCP server URL: `https://public.heypocketai.com/mcp` 4. Click **Connect** and finish the OAuth flow **API key (manual config):** 1. Open config file: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add this configuration: ```json { "mcpServers": { "pocket": { "command": "npx", "args": [ "-y", "mcp-remote", "https://public.heypocketai.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer pk_your_api_key_here" } } } } ``` 3. Restart Claude Desktop. 4. Look for the 🔌 icon showing Pocket tools are connected. ### Claude Code (CLI) [#claude-code-cli] Run this command to add Pocket MCP: ```bash claude mcp add pocket --transport http https://public.heypocketai.com/mcp --header "Authorization: Bearer pk_your_api_key_here" ``` Or add manually to `~/.claude/settings.json`: ```json { "mcpServers": { "pocket": { "type": "http", "url": "https://public.heypocketai.com/mcp", "headers": { "Authorization": "Bearer pk_your_api_key_here" } } } } ``` Restart Claude Code after adding. ### Littlebird [#littlebird] Pocket is available as an official [Littlebird](https://littlebird.ai/) integration. 1. Open Littlebird **Settings** 2. Go to **Integrations** 3. Click **Add integration** 4. Search for **Pocket** and follow the prompts to connect your account ### Windsurf [#windsurf] Add to your Windsurf MCP config (`~/.windsurf/mcp.json`): ```json { "mcpServers": { "pocket": { "command": "npx", "args": [ "-y", "mcp-remote", "https://public.heypocketai.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer pk_your_api_key_here" } } } } ``` ### Cline (VS Code Extension) [#cline-vs-code-extension] 1. Open VS Code Settings 2. Search for "Cline MCP" 3. Add to MCP Servers configuration: ```json { "pocket": { "command": "npx", "args": [ "-y", "mcp-remote", "https://public.heypocketai.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer pk_your_api_key_here" } } } ``` ### Generic MCP Client (Direct HTTP) [#generic-mcp-client-direct-http] For any MCP-compatible client that supports HTTP transport: * **Endpoint**: `https://public.heypocketai.com/mcp` * **Transport**: Streamable HTTP * **Auth Header**: `Authorization: Bearer pk_your_api_key_here` * **Required Headers**: * `Content-Type: application/json` * `Accept: application/json, text/event-stream` ## Available Tools [#available-tools] Some transcript and synthesized-query tools are available on Pro plans only. Search, account info, folders, and folder filtering are available on all plans. | Tool | Plan | Description | | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `search_pocket_conversations` | All plans | Search conversations. With a `query` it returns the most relevant section hits; without a `query` it returns recent full transcripts with pagination. Supports folder filtering with `folderIds` | | `search_pocket_actionitems` | All plans | Search action items with status/priority/category/due date filters | | `update_pocket_actionitem` | All plans | Update an action returned by `search_pocket_actionitems` — change its status (e.g. mark it done), priority, due date, label, context, or assignee | | `get_account_info` | All plans | Return the authenticated user's email, display name, plan (free or pro), and active organization | | `get_pocket_conversation` | Pro only | Fetch full transcripts for specific recordings, including the AI-generated summary (Notes) and signed audio URLs | | `list_pocket_folders` | All plans | List the user's folders and spaces with recording counts | | `query_pocket_meetings` | Pro only | Ask a natural-language question about your meetings; returns a synthesized answer plus the source recording ids | ### Tool Details [#tool-details] **get\_pocket\_conversation** (Pro only) * `recording_ids` (array) — Recording IDs to fetch transcripts for * Response includes: * `recordingId`, `recordingTitle`, `recordingDate`, `recordingTags`, `audioUrl` * `transcriptSegments`: array of transcript segments in seconds with shape `{ text: string, start: number, end: number, speaker?: string }` * `summary`: the AI-generated summary shown in the Notes tab (from the most recent summarization), omitted if no summary exists yet * `transcript` (plain flattened text) is no longer returned Example segment-based response: ```json { "success": true, "data": [ { "recordingId": "rec_123", "recordingTitle": "Weekly Sync", "recordingDate": "2026-03-25T15:04:05Z", "recordingTags": ["meeting", "product"], "transcriptSegments": [ { "text": "Let's review the launch plan.", "start": 0.62, "end": 4.88, "speaker": "Alex" }, { "text": "We should finalize QA by Friday.", "start": 5.21, "end": 9.77, "speaker": "Unknown Speaker 2" } ], "summary": { "...": "AI-generated summary content (Notes tab)" }, "audioUrl": { "signedUrl": "https://...", "expiresIn": 3600, "expiresAt": "2026-03-25T16:04:05Z" } } ] } ``` **search\_pocket\_conversations** This tool operates in two modes depending on whether `query` is provided. * `query` (string, optional) — Semantic + keyword search query. When provided, the tool runs **query mode**; when omitted, it runs **recency mode**. * `recordingDateAfter` (string) — Filter recordings after this date (ISO 8601) * `recordingDateBefore` (string) — Filter recordings before this date (ISO 8601) * `tags` (array) — Filter by tag names * `folderIds` (array) — Filter to recordings in these folder or space ids *Query mode* (`query` provided): hybrid vector + BM25 section search. Returns up to 8 of the most relevant section-level hits with timestamps and summaries. *Recency mode* (`query` omitted): returns the most recent full transcripts within the optional date range, sorted newest-first, with pagination metadata. Recording objects include: * `transcriptSegments`: array of transcript segments with shape `{ text: string, start: number, end: number, speaker?: string }` * `transcript`: flattened speaker-prefixed text retained for compatibility Recordings that have not been transcribed yet are included with `transcriptAvailable: false` and an empty transcript. Recency mode also accepts `cursor` for paging. If `data.meta.hasMore` is true, call again with the same filters and set `cursor = data.meta.nextCursor` to fetch the next older page. **list\_pocket\_folders** * No parameters * Response includes the user's spaces and child folders, each with `id`, `name`, `kind` (space or folder), parent folder id, and recording counts (`recordingCount` / `totalRecordingCount`) **query\_pocket\_meetings** (Pro only) * `query` (string, required) — Natural-language question about your meetings and recordings * `language` (string, optional) — Response language, e.g. `"English (US)"` * Response includes: * `answer`: the synthesized natural-language answer * `sourceRecordings`: the recordings the assistant used to answer **get\_account\_info** * No parameters * Response includes `userId`, `email`, `displayName`, `plan` (e.g. `free` or `pro`), `tier` (`free` or `pro`), and `organization` (when the user belongs to one) **search\_pocket\_actionitems** * `query` (string) — Search term within action item title/description * `status` (string) — TODO, IN\_PROGRESS, COMPLETED, CANCELLED * `priority` (string) — CRITICAL, HIGH, MEDIUM, LOW * `category` (string) — TASK, MEETING, REMINDER * `dueBefore` (string) — Filter items due before date (ISO 8601) * `dueAfter` (string) — Filter items due after date (ISO 8601) * `recordingDateFrom` (string) — Filter source recordings after this date (ISO 8601) * `recordingDateTo` (string) — Filter source recordings before this date (ISO 8601) **update\_pocket\_actionitem** Write changes back to an action returned by `search_pocket_actionitems`. Only the fields you provide are changed; omit the rest. * `actionItemId` (string, required) — The `actionItemId` from a `search_pocket_actionitems` result * `status` (string) — TODO, IN\_PROGRESS, COMPLETED, CANCELLED. Setting COMPLETED stamps the completion time (and clears it when moving back out of COMPLETED) * `priority` (string) — CRITICAL, HIGH, MEDIUM, LOW * `dueDate` (string) — New due date: a date (e.g. `2026-07-25`) or an ISO 8601 timestamp that includes a timezone (e.g. `2026-07-25T12:00:00Z` or `2026-07-25T12:00:00+05:30`). Pass an empty string to clear it * `label` (string) — New label/title * `context` (string) — New context/description note. Pass an empty string to clear it * `assignee` (string) — New assignee. Pass an empty string to clear it The action item is updated in place, so completions, reprioritizations, and reschedules made from your AI tool show up in the Pocket app just like edits made there. Response includes the updated `actionItemId`, `status`, `priority`, `dueDate`, `label`, `context`, and `assignee`. ## Example Prompts [#example-prompts] Once connected, try asking: * "List my recordings from this week" * "Get the transcript from my last recording" * "What tags do I have in Pocket?" * "Find recordings tagged with ‘meeting’" * "Search for discussions about budget planning" * "What did I talk about regarding the product launch?" * "Find action items related to the Q1 roadmap" * "Mark the follow-up email action from yesterday's sync as done" * "Bump the priority of my open reminders to high and push their due dates to Friday" ## Troubleshooting [#troubleshooting] **Tools not showing up?** * Make sure you restarted the app after adding config * Check that your API key is correct (starts with `pk_`) * Verify the config file JSON is valid **Authentication errors?** * Regenerate your API key in Pocket Settings * Check that your key starts with `pk_` * If using `mcp-remote`, confirm you are forwarding the `Authorization` header with `--header` * Make sure there are no extra spaces or newlines in the key value ## MCP FAQ [#mcp-faq] ### What is the Pocket MCP server URL? [#what-is-the-pocket-mcp-server-url] Use `https://public.heypocketai.com/mcp` as the Pocket MCP server URL. ### Should I use OAuth or an API key? [#should-i-use-oauth-or-an-api-key] Use OAuth when your MCP client supports it. Use an API key when your client only supports static headers or command-line configuration. ### Which tools can connect to Pocket MCP? [#which-tools-can-connect-to-pocket-mcp] Pocket MCP works with MCP-compatible clients, including Claude, Cursor, Littlebird, and other AI tools that support remote MCP servers. ### What can AI tools access through Pocket MCP? [#what-can-ai-tools-access-through-pocket-mcp] Authorized tools can search and read your Pocket recordings, transcripts, and related context according to the permissions granted by your authentication method. This is our first release – feedback welcome! Let us know what’s working and what needs improvement. # API Reference Welcome to the Pocket Public API documentation. Build integrations and access your recordings programmatically. ## Base URL [#base-url] ``` https://public.heypocketai.com/api/v1 ``` ## Authentication [#authentication] All API requests require authentication via Bearer token in the `Authorization` header. Use your API key (`pk_xxx`): ```bash curl -X GET "https://public.heypocketai.com/api/v1/public/recordings" \ -H "Authorization: Bearer pk_xxx" ``` ## Endpoints [#endpoints] ### Search [#search] Use semantic search to find relevant content across all your recordings, transcripts, and AI-generated summaries. ### Recordings [#recordings] ### Tags [#tags] ### Organization [#organization] ### Webhooks [#webhooks] ## API FAQ [#api-faq] ### What can I build with the Pocket API? [#what-can-i-build-with-the-pocket-api] You can build integrations that search recordings, list recordings, fetch recording details, access transcripts and summaries, manage tags, and respond to webhook events. ### How do I authenticate Pocket API requests? [#how-do-i-authenticate-pocket-api-requests] Create an API key in Pocket and send it in the `Authorization` header as `Bearer pk_xxx`. ### Does the API support semantic search? [#does-the-api-support-semantic-search] Yes. Use the search endpoint to find relevant recordings, transcripts, and AI-generated summaries across your Pocket data. ### Can I receive events when recordings change? [#can-i-receive-events-when-recordings-change] Yes. Use [Pocket Webhooks](/docs/api/webhooks) to receive event notifications for recordings and related resources. # Join Community ## The fastest way to get better with Pocket [#the-fastest-way-to-get-better-with-pocket] Meet founders, creators, and power users who ship fast and share sharper workflows. Learn what's working, ask questions, and swap setups that save time. [Join now](https://community.heypocket.com/invites/EbFNUvxXPY) *** ## Why join [#why-join] * **Real-world playbooks.** See how people use Pocket across meetings, research, sales, and building. * **Direct line to the team.** Roadmap previews, betas, and AMAs. * **Faster answers.** Get help from people who've already solved your exact issue. * **Give feedback, shape features.** Your posts influence what ships next. *** ## What you'll get inside [#what-youll-get-inside] * Quick fixes from the community and team * Upvote ideas, track status * What's new, what changed, what's next * Share your setup; learn from others *** ## 2-minute setup [#2-minute-setup] 1. **Open the invite**: [Pocket Community](https://community.heypocket.com/invites/EbFNUvxXPY) 2. **Create your profile** (name + role). 3. **Introduce yourself** with the template below. 4. **Turn on notifications** for release notes and announcements. *** ## First post template (copy and paste) [#first-post-template-copy-and-paste] **Who I am:** (Founder, PM, student, etc.) **How I'll use Pocket:** (meetings, lectures, field notes…) **My setup:** (iOS/Android, habits) **One question:** (what's the best way to…?) **One request:** (I'd love a mode that…) *** ## Feature requests and improvements [#feature-requests-and-improvements] Don't see a feature or have an improvement in mind? **Add it at** [**feedback.heypocket.com**](http://feedback.heypocket.com/) Please **search first** and **upvote** existing ideas, high-signal items are prioritized on our roadmap. *** ## House rules [#house-rules] * **Be clear. Be kind.** Short, helpful replies beat long rants. * **Share reproducible steps** for issues. * **No spam, no self-promo**. * **Respect privacy.** Don't post sensitive recordings or personal info. *** ## If you get stuck [#if-you-get-stuck] * Invite link not working? Try again in a private window, or message support with your email and a screenshot. * Need account help? Email [hey@heypocket.com](mailto:hey@heypocket.com) with subject **"Community Access"**. *** ## You're in good company [#youre-in-good-company] This is where Pocket gets sharper, because you're here. **Join now** [**Pocket Community**](https://community.heypocket.com/invites/EbFNUvxXPY) # Your Day 1 with Pocket ## 1) Choose your lens (takes 10 seconds) [#1-choose-your-lens-takes-10-seconds] Pick a Summary style in your profile section so Pocket knows what you're doing. Keep it simple: * **Meeting** for team stuff. * **Discovery Call** for sales or partners. * **Interview** for hiring or research. * **Journaling** for thinking out loud. * **Auto Detect** if you're not sure. You can change it later. Pocket will re-summarize. It just works. *** ## 2) Talk so Pocket can help [#2-talk-so-pocket-can-help] Use plain labels out loud: * "**Decision:** ship bug fix only." * "**Action item:** Jamie sends the deck by Friday 5pm." * "**Risk:** login flow breaks on Android." Pocket hears that. It pins it. It shows up in your mind map and your action list. *** ## 3) Put actions on your calendar (one tap) [#3-put-actions-on-your-calendar-one-tap] When Pocket surfaces tasks, tap **Add to Calendar**. Set the time. Done. Connect your calendar in **Calendar Tab → Add Calendar** if you haven't yet. This is how talk becomes follow-through. *** ## Your Day One plan (real life, not theory) [#your-day-one-plan-real-life-not-theory] ### Morning – 90 seconds of clarity [#morning--90-seconds-of-clarity] Say: "Three priorities today are… Action item: schedule investor follow-up Thursday 9am." Open the note → tap **Add to Calendar**. That's your first domino. ### First meeting – make the decision stick [#first-meeting--make-the-decision-stick] In the room: "Decision… Action item…" Afterwards, open the note → **Mind Map** → tap the tasks → **Add to Calendar**. Now the team has a summary you can paste into Slack, and time-boxed next steps. ### Walking 1:1 – human, crisp [#walking-11--human-crisp] Say: "One win, one worry, one ask." Add exactly one action to the calendar before you put your phone away. ### Sales or partner call – move it forward [#sales-or-partner-call--move-it-forward] Say: "Discovery… Next step: send pricing, book pilot kickoff." Turn "send pricing" into a calendar event before the tab is closed. ### Solo deep work – think out loud, get structure back [#solo-deep-work--think-out-loud-get-structure-back] Say: "Pricing: assumptions, counter-arguments, tests." Open the **Mind Map**. Collapse it to three nodes. Create one 45-minute calendar block to tackle the first node. ### Afternoon – the two-minute sweep [#afternoon--the-two-minute-sweep] Open **Today**. Anything important that doesn't have a time yet? Tap **Add to Calendar**. Close the loop. ### Evening – set tomorrow in motion [#evening--set-tomorrow-in-motion] Say: "One win. One lesson. First domino for tomorrow at 9am." Add that domino to your calendar. Sleep easy. *** ## What you'll see (and why it matters) [#what-youll-see-and-why-it-matters] * **Summary** you can paste anywhere without edits. * **Action items** that link back to the exact moment. * **Mind map** that shows the big picture at a glance. *** ## If Sync Faster acts up [#if-sync-faster-acts-up] Toggle Bluetooth and Wi-Fi. Close and reopen the app. Still stuck? **Reset your phone's network settings** and try again. * **iPhone:** Settings → General → Transfer or Reset iPhone → **Reset Network Settings** * **Android:** Settings → System → Reset options → **Reset Wi-Fi, mobile & Bluetooth** (You'll rejoin Wi-Fi and re-pair Bluetooth afterward.) *** ## The Day One rule [#the-day-one-rule] Don't leave the app until your important actions have times on your calendar. That's how Pocket pays for itself, on day one. # Download the App ## Desktop Beta [#desktop-beta] > The desktop app is currently in beta. If something doesn't work as expected, let us know in the [community](https://community.heypocket.com/invites/dhBxWgnids) or email **[hey@heypocket.com](mailto:hey@heypocket.com)**. **macOS:** Universal installer for Apple Silicon and Intel Macs. Download for macOS **Windows 10+:** Download for Windows **Installation:** Open the `.dmg` file on macOS and drag Pocket to your Applications folder. On Windows, run the `.exe` installer and follow the prompts. Use the desktop app to [record Zoom, Microsoft Teams, and Google Meet calls](/docs/getting-started/record-zoom-teams-google-meet) with microphone and system audio, without adding a meeting bot. > **First launch on macOS:** If you see "App can't be opened", right-click the app, select **Open**, then click **Open** again. This is a one-time macOS Gatekeeper prompt for apps downloaded outside the App Store. ## Mobile [#mobile] * **iPhone (App Store):** [Download from App Store](https://apps.apple.com/us/app/pocket-ai-thought-companion/id6746845735) * **Android (Google Play):** [Download from Play Store](https://play.google.com/store/apps/details?id=com.heypocket.app) > Tip: If search shows many "Pocket" apps, use the links above to get the correct one. *** ## Optional: Share your unboxing [#optional-share-your-unboxing] We'd love to see your first moments with Pocket. Post a short unboxing video and your first reactions in our community thread: [**Unbox with us**](https://community.heypocket.com/t/unbox-with-us-share-your-first-moments-with-pocket/140?u=akshay) We won't use your video for marketing unless you **explicitly** say yes, feel free to add a line in your post like "Approved to share." *** ## What's next [#whats-next] Head to Step 1: **[Unboxing Pocket](/docs/getting-started/unboxing)** to meet your device and take a quick tour. *** ## Need help? [#need-help] * Post in the [community](https://community.heypocket.com/invites/dhBxWgnids) * Or email **[hey@heypocket.com](mailto:hey@heypocket.com)** with your order email and a screenshot of the issue # Pairing your Pocket Getting Started with Your Pocket Device Setup > Use the same email you used to purchase Pocket when signing into the app. Subscriptions are tied to your purchase email, not the device. ## Get the app [#get-the-app] > Install Pocket on your phone to finish setup. *** ## Turn on Pocket [#turn-on-pocket] Your new Pocket ships in **sleep mode**. 1. **Press and hold** the **side button** for **5 seconds**. 2. The light begins **blinking blue,** that means Pocket is **ready to pair** with the app. > If the light doesn't turn on, give Pocket 10 minutes of charge and try again. *** ## Sign in to the app [#sign-in-to-the-app] 1. Open the **Pocket** app. 2. Choose **Continue with Google/Apple** or **Use email**. 3. If you use email, you'll receive a **one-time password (OTP),** copy it into the app to sign in. > You'll be asked a few quick questions (like your role) to personalize your experience. *** ## Allow permissions [#allow-permissions] For the best experience, allow: * **Bluetooth** (connects your Pocket) * **Wi-Fi** (syncs and updates) * **Location** (helps with device discovery on some phones) * **Notifications** (so you don't miss summaries and updates) > You can also connect Google Calendar to link meetings with recordings *** ## Choose your language [#choose-your-language] Select the language you speak most often. This is used for **transcriptions** and **AI summaries**. > You can change this anytime in Settings → Summary Language. *** ## Pair your Pocket [#pair-your-pocket] 1. Make sure Pocket's light is **blinking blue**. 2. When you see your Pocket, **select it**. 3. The light turns **solid blue,** you're device is paired with app and ready. > If you see multiple devices, pick the one that matches your device color or turn off the other one until pairing is done. *** ## Slider check (quick practice) [#slider-check-quick-practice] During onboarding, the app will ask you to toggle the slider: * **Up — Call mode** *(no speaker mode needed)* * **Down — Conversation mode** You can change this anytime from the device before recording. > After a call, stop the recording and switch Down to Conversation. The contact mic in Call mode is ultra-sensitive and can pick up surface noise if you leave it on. *** ## Create your voice print (optional) [#create-your-voice-print-optional] This helps Pocket **recognize your voice** in future recordings. 1. Tap **Start voice print** in the app. 2. Read the sample lines on screen (numbers, words, a short phrase). 3. The recording **stops automatically** and your sample is uploaded for processing. > You can skip this now and set it up later in Settings → Regenerate voice print. *** ## Quick fixes [#quick-fixes] * **Can't see Pocket in the app?** Toggle your phone's **Bluetooth off → on**, then reopen the app. * **Still not pairing?** **Hold the side button for 5 seconds** to turn off Pocket, then hold again for 5 seconds to turn on then try again. * **Light won't blink?** Charge for **10 minutes**, then hold the side button **5 seconds**. *** ## Accessibility notes [#accessibility-notes] * The **side button** powers on/off and starts/stops recordings. * The **light** communicates state: **blinking blue** (ready to pair), **solid blue** (connected), **amber** (recording), **green/pulse** (charging). ## Pairing FAQ [#pairing-faq] ### What does the blinking blue light mean? [#what-does-the-blinking-blue-light-mean] Blinking blue means Pocket is ready to pair. Open the Pocket app, keep the device near your phone, and select it from the pairing screen. ### What if the app does not see my Pocket? [#what-if-the-app-does-not-see-my-pocket] Confirm Bluetooth is enabled, grant the Pocket app Bluetooth permission, keep the device within a few feet of your phone, and restart Pocket by holding the side button for 5 seconds. ### What if Pocket turns solid blue but the app gets stuck? [#what-if-pocket-turns-solid-blue-but-the-app-gets-stuck] Force-close the Pocket app on every phone where you are logged in, hardware-reset the device, reopen the app, and stay on the pairing screen until setup advances. ### Which email should I use during setup? [#which-email-should-i-use-during-setup] Use the same email you used to purchase Pocket. Subscriptions and Pro access are tied to your purchase email, not to the physical device. # Record Zoom, Microsoft Teams, and Google Meet The Pocket desktop app can record the audio from **Zoom**, **Microsoft Teams**, and **Google Meet** calls on macOS and Windows. Pocket captures your microphone and the meeting audio playing through your computer, then turns the conversation into a transcript, summary, and action items. Pocket records locally through the desktop app. It does not add a recording bot or extra participant to your meeting. ## Before your meeting [#before-your-meeting] 1. [Download the Pocket desktop app](/docs/getting-started/download-app) for macOS or Windows. 2. Sign in to Pocket and allow the microphone and system-audio permissions requested by your computer. 3. In **Settings → General → Recording**, leave **Meeting Detection** on if you want Pocket to notify you when a supported call starts or ends. 4. Turn on **Auto Record** if you want Pocket to begin recording automatically after it detects a supported meeting. Auto Record is optional. ## Record a Zoom, Teams, or Google Meet call [#record-a-zoom-teams-or-google-meet-call] 1. Join the call in the meeting app or your browser. 2. Start recording from Pocket, accept the meeting-detection notification, or use Auto Record. 3. End the recording when the meeting finishes. If Meeting Detection started the recording, Pocket can notify you when the call ends. 4. Wait for the recording to upload and process, then open it in Pocket to review the transcript, summary, and action items. ## What Pocket records [#what-pocket-records] Pocket records: * Your microphone, including your side of the conversation * System audio, including the other people speaking through Zoom, Teams, or Google Meet * Audio used to create the transcript, summary, and action items Pocket does **not** record meeting video, webcams, chat messages, or shared-screen content. If system-audio capture is unavailable, Pocket continues recording the microphone instead of failing the entire recording. Check the system-audio level before relying on the recording for an important call. ## Recording tips [#recording-tips] * Wear headphones when possible to reduce echo and prevent the microphone from picking up your speakers. * Keep the Pocket desktop app running for Meeting Detection and Auto Record to work. * Start Pocket before joining an important meeting so you have time to approve any operating-system permission prompts. * Make a short test recording after installing Pocket or changing microphones, headphones, or speakers. ## Frequently asked questions [#frequently-asked-questions] ### Can Pocket record Zoom meetings? [#can-pocket-record-zoom-meetings] Yes. The Pocket desktop app can capture your microphone and Zoom meeting audio on macOS and Windows, without adding a bot to the call. ### Can Pocket record Microsoft Teams meetings? [#can-pocket-record-microsoft-teams-meetings] Yes. Pocket supports Microsoft Teams calls in the desktop app and recognized browser meetings. Start the recording manually, use the meeting notification, or enable Auto Record. ### Can Pocket record Google Meet calls? [#can-pocket-record-google-meet-calls] Yes. Join Google Meet in a supported browser and use the Pocket desktop app to record your microphone and system audio. ### Does Pocket automatically record every meeting? [#does-pocket-automatically-record-every-meeting] Only if you enable **Auto Record** under **Settings → General → Recording**. With Meeting Detection on and Auto Record off, Pocket asks before it starts recording. ### Does a Pocket bot join the meeting? [#does-a-pocket-bot-join-the-meeting] No. Pocket records audio through the desktop app, so no bot appears in the participant list. ### Do I need permission to record a meeting? [#do-i-need-permission-to-record-a-meeting] Recording-consent laws and company policies vary. Tell participants when required and get the necessary consent before recording. # Learn about the status light *What each color and pattern means at a glance* | Light | What it means | When you'll see it | | --------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- | | **Blinking blue** | Ready to pair | After turning Pocket on and it's searching for the app to pair | | **Solid blue** | Paired and ready | idle/standby | | **Solid amber** | Recording | When you press the side button once or start recording from the app | | **Solid white** | Paused | After you pause a recording from the app or double-press the side button | | **Blinking green** | Charging | While connected to power via USB-C | | **Solid green** | Fully charged | Stays solid when the battery is full and still on charge | | **Green / Amber / Red** (after **double-pressing side button**) | Battery level | Quick battery check: green = full, amber = about half, red = low | | **Blinking red** (during reset flow) | Reset triggered | After **triple-press** then **hold** to erase and return to setup or pairing mode | | **Blinking purple** | Firmware update | During an update initiated from the app | | **No light** | Off or asleep | Pocket is powered off or in sleep | *** ## Interaction lights (everyday use) [#interaction-lights-everyday-use] * **Turn on / off:** **Hold 5 seconds** on the side button. * **Ready to pair:** **Blinking blue.** * **Ready:** **Solid blue.** * **Recording:** **Solid amber.** * **Paused:** **Solid white.** See [Pause and Resume](/docs/features/productivity/pause-recording). *** ## Charging and battery [#charging-and-battery] * **Charging:** **Blinking green.** * **Fully charged:** **Solid green.** * **Quick battery check:** **Double-press** the side button * **Green** = full * **Amber** = about half * **Red** = low, charge with USB-C *** ## Updates and reset (only if needed) [#updates-and-reset-only-if-needed] * **Firmware update:** LED **blinks purple** until complete; Pocket restarts automatically. * **Factory reset:** **Triple-press**, wait for **red** to start blinking, then **hold** while it blinks to erase and return to setup. *** ## Tips [#tips] * If you don't see any light, **charge for 10 minutes** and try **hold 5 seconds** again. * If it stays **blinking blue** for more than 30 seconds, open the app and start pairing. # Troubleshooting Short, practical fixes for the most common issues. Try these in order. *** ## Quick checks (fix most problems fast) [#quick-checks-fix-most-problems-fast] 1. **Charge Pocket** for 15+ minutes, then try again. 2. **Restart Pocket:** hold the side button for 5 seconds to turn off, wait 10 seconds, turn it on (hold 5 seconds). 3. **Restart your phone** and **force-quit/reopen** the Pocket app. 4. **Update the app** from the App Store / Play Store. 5. **Turn Bluetooth OFF → ON** and **Wi-Fi OFF → ON** on your phone. *** ## Can't sign in / OTP not received [#cant-sign-in--otp-not-received] * Check **spam/junk** for the code. * Tap **"Resend code"** after 30 seconds. * If you purchased Pocket, **sign in with the same email used at checkout** (subscriptions are tied to your purchase email, not the device). * Still stuck? Try a secondary sign-in method (Apple/Google) with the **same purchase email**. *** ## Device won't turn on [#device-wont-turn-on] * Charge with a known-good USB-C cable & adapter. * Try a different outlet/adapter. * Hold the **side button for 5 seconds** to power on. * If no LED ever shows, leave it charging for 30 minutes and try again. *** ## Pairing screen stuck after selecting device (solid blue, app doesn't advance) [#pairing-screen-stuck-after-selecting-device-solid-blue-app-doesnt-advance] If your Pocket turns **solid blue** right after you tap it in the app, but the pairing screen **doesn't move forward**, do this: 1. On **all** phones where you're logged into Pocket, **force‑close** the app (remove from background). 2. Hardware Reset (device): **Triple-click the side button** (LED blinks red), **immediately press and hold** the side button until the **red blinking stops**, then **release when the LED returns to breathing blue**. 3. Reopen the app and pair again. **Stay on the pairing screen** for a moment, don't switch apps until it advances. 4. If it stalls again, **toggle Bluetooth off/on** (phone), or **reboot** the phone, then repeat steps 1–3. > Why it happens: in rare cases the app connects (device goes solid blue) but the UI doesn't progress. A quick hardware reset + app restart clears it. *** ## Can't pair / app doesn't see Pocket (Bluetooth) [#cant-pair--app-doesnt-see-pocket-bluetooth] 1. Make sure Pocket is **blinking blue** (ready to pair). If not, turn Pocket off/on. 2. Turn **Bluetooth ON** and grant the app **Bluetooth permission**. 3. **Forget** any old "Pocket" entries in your phone's Bluetooth list, then re-pair from **inside the Pocket app**. 4. Move away from other Bluetooth devices; keep phone within 1–2 ft. 5. Toggle **Airplane Mode ON → OFF**. *** ## Wi-Fi Quick Sync not working / Won't connect to Pocket (network) [#wi-fi-quick-sync-not-working--wont-connect-to-pocket-network] 1. Ensure **Wi-Fi is ON** and stable; avoid captive portals (hotel/guest Wi-Fi). 2. Disable **VPN**, **Private Relay**, **Low Data Mode**, or **battery saver** (can block local sync). 3. On iOS, allow **Local Network** permission for the Pocket app (Settings → Pocket → enable Local Network & Bluetooth). 4. **Update Pocket's Wi-Fi firmware:** open the app → **Profile / Settings → Check for Wi-Fi firmware** → install any available update, then retry Quick Sync. 5. Keep the app open in the foreground. If a file is stuck or missing, use the home screen three-dot menu → **Resync From Device**. **Important fix:** * Start here for the built-in docs guide: [**Wi-Fi Sync Troubleshooting**](/docs/features/device/wifi-sync-troubleshooting) * **If Wi-Fi Sync hangs in between:** Follow this 2-minute guide → [**Fix Pocket Wi-Fi Sync Hang**](https://scribehow.com/viewer/Pocket_Wi-Fi_Sync_Troubleshooting_for_iPhone__bFnTB1VNRn2eTGDBAafGTw) * **If Wi-Fi firmware update hangs in between:** Follow this 2-minute guide → [**Fix Pocket Wi-Fi firmware update Hang**](https://scribehow.com/viewer/Pocket_Wi-Fi_Firmware_Update_Troubleshooting_for_iPhone__9_h32FQ0Q5aPISWoWMhgpw) *** ## Records won't start / button press does nothing [#records-wont-start--button-press-does-nothing] * Press the **side button once**; you should hear a **beep** and the LED turns **amber** (recording). * If no response: restart Pocket (power off/on), then try again. * Ensure the app isn't actively updating firmware. *** ## Audio is too quiet / noisy [#audio-is-too-quiet--noisy] * Keep Pocket unobstructed (don't cover mics). * Reduce wind/noise; avoid rubbing against clothing. * Speak toward the device within arm's length. * If using a phone case/mount, make sure it isn't blocking mic ports. * For best quality, avoid extremely loud environments. *** ## Transcripts missing or slow [#transcripts-missing-or-slow] * Confirm **internet connectivity**. * Open the app to trigger upload/processing. * Large or long recordings can take longer; leave the app open on foreground. * If you used a **different email**, transcripts tied to your purchase email may not appear, **sign in with your purchase email**. * If still delayed, check the [community](https://community.heypocket.com/) for known issues. *** ## Subscription not recognized [#subscription-not-recognized] * **Sign in with the email used to buy Pocket** (subscriptions follow your purchase email). * If you used Apple/Google SSO with a different email, sign out and sign in with the **purchase email**. * If you changed emails after purchase, contact [support](mailto:hey@heypocket.com) with proof of purchase. *** ## Firmware update failed / stuck [#firmware-update-failed--stuck] * Keep Pocket **charged** and phone near the device. * Ensure **Bluetooth + Wi-Fi** are on; disable VPN. * Restart Pocket and the app, then retry the update. * Don't leave the app during firmware install. *** ## App crashes or freezes [#app-crashes-or-freezes] * Force-quit and reopen the app. * **Update** to the latest version. * Restart your phone. * If reproducible, screen-record the steps and send to support. *** ## Notifications not arriving [#notifications-not-arriving] * Enable notifications for the Pocket app in system settings. * Disable Focus/Do Not Disturb. * On Android, disable battery optimization for Pocket. *** ## LED quick reference [#led-quick-reference] * **Blinking Blue:** ready to pair * **Solid Blue:** paired/idle * **Solid Amber:** recording * **Solid White:** paused (see [Pause and Resume](/docs/features/productivity/pause-recording)) *** ## Legal / call capture note [#legal--call-capture-note] Call/phone-audio capture may be restricted in your region. **Always obtain consent** and check local laws before recording calls. *** ## Still need help? [#still-need-help] * Post in [community](https://community.heypocket.com/) with: phone model & OS, app version, Pocket LED state, what you tried, and a short screen recording if possible. * Or email [**hey@heypocket.com**](mailto:hey@heypocket.com) with the same details and your order number. # In the Box *A quick look at what's included and where it goes* > Use the same email you used to purchase Pocket when signing into the app. Subscriptions are tied to your purchase email, not the device. ## Get the app [#get-the-app] > Install Pocket on your phone to finish setup. *** ## What's included [#whats-included] * **Pocket** (aluminum unibody) * **USB-C cable** (braided) * **Quick Start Guide** with a **QR code** to all setup videos and guides * **Magnetic ring adapter** (for phones without MagSafe) > Scan the QR on the Quick Start card to jump to the Pocket Guide: unboxing, pairing, and Day 1. *** ## A closer look at Pocket [#a-closer-look-at-pocket] * **Design:** Precision-milled aluminum, seamless unibody. * **Side button:** Hold for 5 Seconds for Power on/off; press once to start/stop recording. * **Slider button:** * **Up - Call mode:** Records phone calls via contact mic; no speaker mode needed. Keep Pocket attached to **your phone** using Magsafe during the call. * **Down — Conversation mode:** Slider down for in-person conversations. **After a call:** **Stop** the recording, then slide **Down** to Conversation. *(Call mode's contact mic is ultra-sensitive and can pick up surface noise if left on.)* *** ## The Quick Start Manual (with QR) [#the-quick-start-manual-with-qr] The manual includes: * A labeled diagram of Pocket's button and light * A QR code linking to all setup videos (including this one) * A short Day 1 guide so you can start capturing right away > Tip: Keep the card in the box or save a photo of the QR for later. *** ## USB-C charging cable [#usb-c-charging-cable] A durable, braided **USB-C to USB-C** cable is included. * Use any standard USB-C power adapter * If Pocket doesn't turn on right away, give it **10 minutes of charge** and try again *** ## Magnetic ring adapter (for non-MagSafe phones) [#magnetic-ring-adapter-for-non-magsafe-phones] If your phone doesn't have built-in MagSafe: 1. **Clean** the back of your phone or case 2. **Center** the ring using your camera as a guide 3. **Adhere** the ring and press firmly for a few seconds 4. Pocket now **snaps** into place magnetically > Works with all Android phones and non-MagSafe iPhones. *** ## Accessibility notes [#accessibility-notes] * Pocket has one primary **side button** and a small **status light** on the face * The light blinks **blue** when ready to connect, turns **solid blue** when connected, and glows **amber** while recording # How to Customize Summary Templates Pocket AI allows you to customize how your conversations are summarized by creating custom templates. This guide walks you through the process with annotated screenshots. ## What You'll Learn [#what-youll-learn] * How to access summary customization settings * How to create a custom summary template * How to define custom sections with specific AI instructions * Best practices for template design ## Prerequisites [#prerequisites] * Pocket AI app installed and set up * Active Pocket Pro subscription (for custom templates) ## Step-by-Step Guide [#step-by-step-guide] ### Step 1: Navigate to Summary Settings [#step-1-navigate-to-summary-settings] Open the Pocket app and go to **Settings** (bottom right tab), then tap on **Summary**. The Summary option shows "How your conversations are summarized" as the description. *** ### Step 2: Open Summary Theme Settings [#step-2-open-summary-theme-settings] On the Summary settings page, tap **Summary theme** to access template options. You'll see various configuration options including Language, Summary model, Speaker management, and more. *** ### Step 3: Create New Template [#step-3-create-new-template] On the Summary Theme page, tap **+ Create new template** at the top. You'll also see preset templates like Auto Detect, Meeting Summary, Call Summary, and more. *** ### Step 4: Enter Template Name and Global Instructions [#step-4-enter-template-name-and-global-instructions] The template creation form has three main parts: 1. **NAME** - Give your template a descriptive name (e.g., "Business Meetings") 2. **GLOBAL INSTRUCTIONS** - Provide overall context for how to summarize conversations 3. **SECTIONS** - Define custom sections with specific instructions In the example above: * Template name: "Business Meetings" * Global instruction: "Give an overall context of summarizing your conversations" * First section: "Tone of meeting:" with instruction "Explain overall tone of meeting in 2-3 sentences" *** ### Step 5: Add Multiple Sections [#step-5-add-multiple-sections] Add as many sections as needed to structure your summary. Each section can have: * A **Section Title** (e.g., "Key discussion topics", "Decision Made") * Specific **Instructions** for what the AI should include in that section Sections can be reordered using the drag handle on the left. *** ### Step 6: Add More Sections and Save [#step-6-add-more-sections-and-save] Use the **+ Add Section** button to add more sections as needed. Once your template is complete, tap **Create template** to save it. In the example: * "Action Items and Deadlines" section * "Unresolved Question" section * "+ Add Section" button to add more * "Create template" button to save *** ## Template Design Tips [#template-design-tips] ### 1. Be Specific with Instructions [#1-be-specific-with-instructions] Instead of vague instructions like "summarize the meeting," use specific guidance: **Good:** "List 3-5 key decisions made, including who made each decision" **Better:** "Extract action items with assigned person and deadline in format: \[Person] - \[Task] - \[Due date]" ### 2. Structure Your Sections Logically [#2-structure-your-sections-logically] Organize sections in a natural flow: 1. Overview/Context 2. Main Discussion Points 3. Decisions Made 4. Action Items 5. Next Steps ### 3. Use Consistent Section Names [#3-use-consistent-section-names] If you create multiple templates, use consistent section names for similar content. This makes it easier to find information across different conversation types. ### 4. Leverage Global Instructions [#4-leverage-global-instructions] Use the global instructions field to set the overall tone and style: * "Use bullet points and concise language" * "Write in a formal business tone" * "Focus on actionable insights" ### 5. Template Examples by Use Case [#5-template-examples-by-use-case] **For Meetings:** * Attendees * Agenda Items Covered * Key Decisions * Action Items & Owners * Next Meeting Date **For Interviews:** * Candidate Background * Questions Asked * Candidate Responses (by topic) * Strengths Observed * Concerns/Red Flags * Recommendation **For Journaling:** * Mood/Emotional State * Key Events Today * Reflections & Insights * Gratitude Items * Goals for Tomorrow *** ## Related Features [#related-features] * [Recording & Summary](/docs/features/summary) - Learn about Pocket's summary capabilities * [Custom Templates](/docs/features/templates) - Overview of template features * [Pocket Pro](/docs/features/pocket-pro) - Learn about Pro subscription benefits ## Need Help? [#need-help] If you have questions about custom templates, visit the [Pocket Community](https://community.heypocket.com) or contact support. # Pocket Pro **Pocket Pro** is a premium subscription designed for power users who want the most out of their documentation and AI interactions. ## Key Hero Features [#key-hero-features] * **Unlimited AI Chat**: Interact with "Ask Pocket" as much as you need without daily limits. * **Long Recording Support**: Transcribe and summarize conversations that last up to 4 hours. * **Advanced Templates**: Access and create unlimited custom AI summary templates. * **Priority Processing**: Your recordings are moved to the front of the queue for faster summarization. * **Bulk Actions**: Export, merge, or delete multiple recordings simultaneously. ## Subscription Management [#subscription-management] You can manage your Pocket Pro subscription directly within the app: 1. **Settings**: Go to the **Profile** tab. 2. **Subscription**: Tap on **Pocket Pro** or **Manage Subscription**. 3. **App Store / Shopify**: Depending on where you started your trial, you'll be directed to the Apple App Store, Google Play Store, or our Shopify portal to manage your renewal or billing details. ## Choosing Your Plan [#choosing-your-plan] We offer flexible billing options for Pro: * **Monthly**: Perfect for short-term projects or trials. * **Annual**: The best value for those using Pocket as their primary productivity tool. > Some features, like "AI Template Generation" and "Multi-Memory Synthesis," require an active Pocket Pro subscription to function. # List folders and spaces {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Get the authenticated user's folder hierarchy with recording counts # Organization Analytics The analytics endpoint returns aggregated recording statistics for your organization, broken down by member. ## Get Analytics [#get-analytics] ``` GET /api/v1/organization/:orgId/analytics ``` **Minimum role:** viewer ### Query Parameters [#query-parameters] | Parameter | Type | Default | Description | | ------------ | ------ | ----------- | -------------------------------------------- | | `start_date` | string | 30 days ago | Start of the reporting period (`YYYY-MM-DD`) | | `end_date` | string | today | End of the reporting period (`YYYY-MM-DD`) | ### Example Request [#example-request] ```bash curl -X GET "https://public.heypocketai.com/api/v1/organization/org_abc/analytics?start_date=2026-03-01&end_date=2026-03-31" \ -H "Authorization: Bearer pk_xxx" ``` ### Response [#response] ```json { "period": { "start_date": "2026-03-01", "end_date": "2026-03-31" }, "totals": { "recordings": 142, "total_duration_seconds": 256800, "summarizations": 138 }, "members": [ { "user_id": "usr_001", "email": "alice@example.com", "name": "Alice Chen", "recordings": 54, "total_duration_seconds": 97200, "summarizations": 52 }, { "user_id": "usr_002", "email": "bob@example.com", "name": "Bob Martinez", "recordings": 88, "total_duration_seconds": 159600, "summarizations": 86 } ] } ``` ### Response Fields [#response-fields] | Field | Type | Description | | ---------------------------------- | ------ | ---------------------------------------- | | `period.start_date` | string | Inclusive start date of the period | | `period.end_date` | string | Inclusive end date of the period | | `totals.recordings` | number | Total recordings across all members | | `totals.total_duration_seconds` | number | Combined duration in seconds | | `totals.summarizations` | number | Total summarizations generated | | `members[].user_id` | string | Member's user ID | | `members[].email` | string | Member's email address | | `members[].name` | string | Member's display name | | `members[].recordings` | number | Recordings created by this member | | `members[].total_duration_seconds` | number | Combined duration for this member | | `members[].summarizations` | number | Summarizations generated for this member | # Organization API Keys Organization API keys provide programmatic access to the Pocket API on behalf of your organization. Keys can be scoped to limit which resources they can access. ## List API Keys [#list-api-keys] ``` GET /api/v1/organization/:orgId/api-keys ``` **Minimum role:** viewer Returns all API keys for the organization. ### Response [#response] ```json { "keys": [ { "id": "key_abc123", "name": "CI Pipeline", "scopes": ["recordings:read", "templates:read"], "created_at": "2026-01-15T10:00:00.000Z", "expires_at": "2026-07-15T10:00:00.000Z", "last_used_at": "2026-04-09T14:32:00.000Z" } ] } ``` ## Get API Key [#get-api-key] ``` GET /api/v1/organization/:orgId/api-keys/:keyId ``` **Minimum role:** viewer Returns details for a single API key. ### Path Parameters [#path-parameters] | Parameter | Type | Description | | --------- | ------ | ---------------------- | | `keyId` | string | The API key identifier | ### Response [#response-1] ```json { "id": "key_abc123", "name": "CI Pipeline", "scopes": ["recordings:read", "templates:read"], "created_at": "2026-01-15T10:00:00.000Z", "expires_at": "2026-07-15T10:00:00.000Z", "last_used_at": "2026-04-09T14:32:00.000Z" } ``` ## Create API Key [#create-api-key] ``` POST /api/v1/organization/:orgId/api-keys ``` **Minimum role:** admin Creates a new API key. The full key value is returned **only once** in the response — store it securely. ### Request Body [#request-body] | Field | Type | Required | Description | | ------------ | --------- | -------- | ------------------------------------------------------- | | `name` | string | Yes | A human-readable label for the key | | `scopes` | string\[] | No | Permissions to grant. Defaults to all scopes if omitted | | `expires_at` | string | No | ISO 8601 expiration date. Omit for a non-expiring key | ### Available Scopes [#available-scopes] | Scope | Description | | ------------------ | ----------------------------------------------------------------------------------- | | `recordings:read` | List and view recordings | | `recordings:write` | Create, update, and delete recordings | | `templates:read` | List and view templates | | `templates:write` | Create, update, and delete templates | | `users:read` | List org users and read another member's settings, profile, and learned preferences | | `users:write` | Update another member's settings, profile, and learned preferences | ### Example Request [#example-request] ```json { "name": "CI Pipeline", "scopes": ["recordings:read", "templates:read"], "expires_at": "2026-07-15T10:00:00.000Z" } ``` ### Response [#response-2] ```json { "id": "key_abc123", "name": "CI Pipeline", "key": "pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "scopes": ["recordings:read", "templates:read"], "created_at": "2026-04-10T08:00:00.000Z", "expires_at": "2026-07-15T10:00:00.000Z" } ``` ## Delete API Key [#delete-api-key] ``` DELETE /api/v1/organization/:orgId/api-keys/:keyId ``` **Minimum role:** admin Permanently revokes an API key. Any request using this key will be rejected immediately. ### Path Parameters [#path-parameters-1] | Parameter | Type | Description | | --------- | ------ | ---------------------- | | `keyId` | string | The API key identifier | ### Response [#response-3] ```json { "success": true } ``` # Organization API The Organization API lets you manage every aspect of your Pocket organization — API keys, shared templates, analytics, recordings, members, and invites. ## Base Path [#base-path] All organization endpoints are scoped under: ``` /api/v1/organization/:orgId/ ``` Replace `:orgId` with your organization's unique identifier. ## Authentication [#authentication] Organization endpoints accept two authentication methods: | Method | Header | Use Case | | -------------------- | ------------------------------------------- | ---------------------------------- | | Firebase token | `Authorization: Bearer ` | Internal apps and admin dashboards | | Organization API key | `Authorization: Bearer pk_xxx` | Programmatic / public API access | Firebase-authenticated requests resolve the caller's org membership and role automatically. API-key requests inherit the scopes assigned to the key. ## Permission Model [#permission-model] Every organization member has one of four roles: | Role | Description | | -------- | -------------------------------------------------------- | | `owner` | Full control including billing and org deletion | | `admin` | Manage members, keys, templates, and recordings | | `viewer` | Read-only access to recordings, analytics, and templates | | `member` | Standard access to recordings and templates | Endpoints note their minimum required role. Actions that modify resources (create, update, delete) typically require **admin** or above; read-only actions are available to **viewer** and above. ## Endpoints [#endpoints] # Organization Invites Invite new members to your organization by email. Invites can be resent or revoked before they are accepted. ## Send Invite [#send-invite] ``` POST /api/v1/organization/:orgId/invites ``` **Minimum role:** admin Sends an email invitation to join the organization. ### Request Body [#request-body] | Field | Type | Required | Description | | ------- | ------ | -------- | -------------------------------------------------- | | `email` | string | Yes | Email address of the invitee | | `role` | string | No | Role to assign on acceptance. Defaults to `member` | ### Example Request [#example-request] ```json { "email": "carol@example.com", "role": "viewer" } ``` ### Response [#response] ```json { "id": "inv_abc123", "email": "carol@example.com", "role": "viewer", "status": "pending", "created_at": "2026-04-10T08:00:00.000Z", "expires_at": "2026-04-17T08:00:00.000Z" } ``` ## Accept Invite [#accept-invite] ``` POST /api/v1/organization/invites/accept ``` **Minimum role:** any authenticated user Accepts a pending invitation using the token from the invite email. The caller is added to the organization with the role specified in the invite. ### Request Body [#request-body-1] | Field | Type | Required | Description | | ------- | ------ | -------- | ---------------------------------------- | | `token` | string | Yes | The invitation token from the email link | ### Example Request [#example-request-1] ```json { "token": "inv_token_xxxxxxxxxxxxxxxx" } ``` ### Response [#response-1] ```json { "org_id": "org_abc", "role": "viewer", "status": "active" } ``` ## Revoke Invite [#revoke-invite] ``` DELETE /api/v1/organization/:orgId/invites/:inviteId ``` **Minimum role:** admin Revokes a pending invitation. The invite link becomes invalid immediately. ### Path Parameters [#path-parameters] | Parameter | Type | Description | | ---------- | ------ | --------------------- | | `inviteId` | string | The invite identifier | ### Response [#response-2] ```json { "success": true } ``` ## Resend Invite [#resend-invite] ``` POST /api/v1/organization/:orgId/invites/:inviteId/resend ``` **Minimum role:** admin Resends the invitation email for a pending invite. ### Path Parameters [#path-parameters-1] | Parameter | Type | Description | | ---------- | ------ | --------------------- | | `inviteId` | string | The invite identifier | ### Response [#response-3] ```json { "success": true } ``` # Organization MCP The Pocket MCP server (`/mcp`) automatically exposes organization-scoped tools alongside your personal conversation tools whenever the request is authenticated against an organization. There is **no separate `/org/mcp` endpoint** — same URL, more tools when org context is available. ## Endpoint [#endpoint] ``` https://public.heypocketai.com/mcp ``` The endpoint speaks the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). ## How org context is resolved [#how-org-context-is-resolved] | Auth method | What appears in tool list | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | **OAuth bearer (Firebase user)** | The 4 personal `*_pocket_*` tools, plus the 12 org tools if you are an active member of at least one organization. | | **User API key** (`Authorization: Bearer pk_user...`) | Same as OAuth. | | **Organization API key** (`Authorization: Bearer pk_org...`) | Only the 12 org tools. No personal conversation tools (the key is not tied to a user). | When you authenticate as a user that belongs to multiple organizations, your **oldest active membership** is selected automatically. There is no per-request org-switching today. ## Permission model [#permission-model] Different gates depending on how you signed in: ### User identity (OAuth or user API key) [#user-identity-oauth-or-user-api-key] The tool is available based on your **role** in the organization: | Role | Read tools | Write tools | | -------- | ---------- | ----------- | | `viewer` | yes | no | | `member` | yes | no | | `admin` | yes | yes | | `owner` | yes | yes | ### Organization API key [#organization-api-key] Gated by the **scopes** assigned to the key when it was created (see [API Keys](/docs/api/organization/api-keys)): | Tool | Scope | | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | `list_org_recordings`, `get_org_recording`, `get_org_recording_audio_url`, `search_org_recordings`, `list_org_tags`, `get_org_analytics` | `recordings:read` | | `list_org_templates`, `get_org_template` | `templates:read` | | `create_org_template`, `update_org_template`, `delete_org_template` | `templates:write` | Calling a tool without the required scope returns `insufficient scope: ` from the tool, not from the transport. ## Tools [#tools] ### Recordings [#recordings] * **`list_org_recordings`** — Paginated list of recordings owned by org members. Supports `start_date`, `end_date` (`YYYY-MM-DD`, filtered on `created_at`), `tag_ids`, `page`, `limit`. * **`get_org_recording`** — Fetch a single recording by `recording_id` with decrypted transcripts and summarizations. * **`get_org_recording_audio_url`** — Generate a pre-signed S3 URL for audio download (`expires_in` 60–86400 seconds, default 3600). * **`search_org_recordings`** — Semantic search across all active organization member recordings (transcripts, meeting sections, action items). Required: `query`. Optional: `limit` (1–20, default 8), `dateFrom`, `dateTo`, `recordingIds`, `tagIds`, `folderIds`. Backed by the per-org Turbopuffer namespaces; new members are dual-written into the org index automatically and a backfill task seeds existing data. ### Tags [#tags] * **`list_org_tags`** — All tags belonging to org members, with usage counts. ### Templates [#templates] * **`list_org_templates`** / **`get_org_template`** — Read the org's shared templates. * **`create_org_template`** — Create a new template. Required: `name`, `sections`. Optional: `description`, `icon`, `meeting_context`, `generate_action_items`, `generate_mind_map`, `category`, `routing_instructions`. When called by a real user, the user is recorded as the template creator. * **`update_org_template`** — Patch fields on an existing template (only provided fields are changed). * **`delete_org_template`** — Soft-delete a template by `id`. ### Analytics [#analytics] * **`get_org_analytics`** — Aggregated recording statistics for the organization, broken down by member, for an inclusive date range (filtered on `created_at`, matching `list_org_recordings`). Defaults to the last 30 days (UTC). Returns `period`, `totals` (recordings / total\_duration\_seconds / summarizations), and per-member rows. ## Client configuration [#client-configuration] ### Claude Desktop / Cursor [#claude-desktop--cursor] Add to your MCP client config (e.g. `claude_desktop_config.json`): ```json { "mcpServers": { "pocket": { "url": "https://public.heypocketai.com/mcp", "headers": { "Authorization": "Bearer pk_your_key_here" } } } } ``` For OAuth-capable clients, point them at the same URL and complete the OAuth flow when prompted; the org tools become visible automatically if your account is in an organization. ### Manual test [#manual-test] ```bash curl -X POST https://public.heypocketai.com/mcp \ -H "Authorization: Bearer pk_xxx" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Errors [#errors] | Status / Tool error | Meaning | | --------------------------------------------------- | ---------------------------------------------------------------------------------- | | `401 unauthorized` | Missing, malformed, or invalid auth header (no API key or OAuth token recognized). | | `429` | Per-key rate limit hit (see `X-RateLimit-*` response headers). | | `this tool requires user authentication` | An org pk\_ key tried to call a personal `*_pocket_*` tool. | | `this tool requires organization context` | A user API key / OAuth token has no active org membership. | | `user is not an active member of this organization` | Membership row was deactivated between auth and tool call. | | `write access requires the admin or owner role` | A `member` or `viewer` tried to call a template write tool. | | `insufficient scope: ` | Org pk\_ key lacks the scope required by the tool. | | `recording not found` / `template not found` | The resource isn't owned by this org or has been deleted. | # Organization Members Use the members endpoint to update roles and statuses for existing organization members. ## Update Member [#update-member] ``` PATCH /api/v1/organization/:orgId/members/:userId ``` **Minimum role:** admin Updates a member's role and/or status within the organization. ### Path Parameters [#path-parameters] | Parameter | Type | Description | | --------- | ------ | -------------------- | | `userId` | string | The member's user ID | ### Request Body [#request-body] | Field | Type | Required | Description | | -------- | ------ | -------- | ------------------------- | | `role` | string | No | New role for the member | | `status` | string | No | New status for the member | ### Valid Roles [#valid-roles] | Role | Description | | -------- | -------------------------------------------------------- | | `owner` | Full control including billing and org deletion | | `admin` | Manage members, keys, templates, and recordings | | `viewer` | Read-only access to recordings, analytics, and templates | | `member` | Standard access to recordings and templates | ### Valid Statuses [#valid-statuses] | Status | Description | | --------- | ---------------------------------- | | `active` | Member can access the organization | | `pending` | Invited but has not yet accepted | | `removed` | Access revoked | ### Example Request [#example-request] ```json { "role": "admin", "status": "active" } ``` ### Response [#response] ```json { "user_id": "usr_002", "email": "bob@example.com", "name": "Bob Martinez", "role": "admin", "status": "active", "updated_at": "2026-04-10T09:00:00.000Z" } ``` # Organization Recordings These endpoints let you manage recordings across your entire organization rather than for a single user. ## List Recordings [#list-recordings] ``` GET /api/v1/organization/:orgId/recordings ``` **Minimum role:** viewer Returns a paginated list of recordings belonging to the organization. ### Query Parameters [#query-parameters] | Parameter | Type | Default | Description | | ----------------- | ------ | ------- | -------------------------------------------------- | | `date` | string | — | Filter to a specific date (`YYYY-MM-DD`) | | `startDate` | string | — | Start of date range (`YYYY-MM-DD`) | | `endDate` | string | — | End of date range (`YYYY-MM-DD`) | | `tagIds` | string | — | Comma-separated tag IDs to filter by | | `tagMode` | string | `any` | `any` or `all` — match any or all provided tags | | `recordedBy` | string | — | Filter by user ID of the recorder | | `recordedByEmail` | string | — | Filter by email of the recorder | | `page` | number | `1` | Page number (1-indexed) | | `limit` | number | `20` | Results per page (max 100) | | `cursor` | string | — | Cursor for keyset pagination (alternative to page) | ### Example Request [#example-request] ```bash curl -X GET "https://public.heypocketai.com/api/v1/organization/org_abc/recordings?startDate=2026-03-01&endDate=2026-03-31&limit=10" \ -H "Authorization: Bearer pk_xxx" ``` ### Response [#response] ```json { "recordings": [ { "id": "rec_abc123", "title": "Team Standup", "duration": 1800, "language": "English", "recorded_by": "usr_001", "tags": ["tag_meeting"], "created_at": "2026-03-15T09:00:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 42, "next_cursor": "eyJpZCI6InJlY18..." } } ``` ## Get Recording [#get-recording] ``` GET /api/v1/organization/:orgId/recordings/:recordingId ``` **Minimum role:** viewer Returns full details for a single recording. ### Path Parameters [#path-parameters] | Parameter | Type | Description | | ------------- | ------ | ------------------------ | | `recordingId` | string | The recording identifier | ### Query Parameters [#query-parameters-1] | Parameter | Type | Default | Description | | --------- | ------ | ------- | --------------------------------------------------------------------------------------------- | | `include` | string | — | Comma-separated list of related resources to include (e.g. `transcript,summary,action_items`) | ### Response [#response-1] ```json { "id": "rec_abc123", "title": "Team Standup", "description": "Weekly sync", "duration": 1800, "language": "English", "recorded_by": "usr_001", "tags": ["tag_meeting"], "created_at": "2026-03-15T09:00:00.000Z", "transcript": [ { "speaker": "Alice", "text": "Let's go over this week's priorities.", "start": 0.0, "end": 3.5 } ], "summary": { "markdown": "## Key Decisions\n\n..." } } ``` ## Update Recording [#update-recording] ``` PUT /api/v1/organization/:orgId/recordings/:recordingId ``` **Minimum role:** admin Updates metadata for a recording. ### Path Parameters [#path-parameters-1] | Parameter | Type | Description | | ------------- | ------ | ------------------------ | | `recordingId` | string | The recording identifier | ### Request Body [#request-body] | Field | Type | Required | Description | | ------------- | --------- | -------- | ------------------- | | `title` | string | No | Updated title | | `description` | string | No | Updated description | | `tags` | string\[] | No | Replacement tag IDs | ### Example Request [#example-request-1] ```json { "title": "Team Standup — Week 12", "tags": ["tag_meeting", "tag_weekly"] } ``` ### Response [#response-2] ```json { "id": "rec_abc123", "title": "Team Standup — Week 12", "description": "Weekly sync", "duration": 1800, "tags": ["tag_meeting", "tag_weekly"], "updated_at": "2026-04-10T09:00:00.000Z" } ``` ## Delete Recording [#delete-recording] ``` DELETE /api/v1/organization/:orgId/recordings/:recordingId ``` **Minimum role:** admin Deletes a recording. By default this is a soft delete; pass `permanent=true` to hard-delete. ### Path Parameters [#path-parameters-2] | Parameter | Type | Description | | ------------- | ------ | ------------------------ | | `recordingId` | string | The recording identifier | ### Query Parameters [#query-parameters-2] | Parameter | Type | Default | Description | | ----------- | ------- | ------- | -------------------------------------------------------------------- | | `permanent` | boolean | `false` | If `true`, permanently deletes the recording and all associated data | ### Response [#response-3] ```json { "success": true } ``` # Organization Templates Organization templates define reusable summarization structures shared across all members. When a template is created at the org level it automatically appears in every member's template list and summarization flows. ## List Templates [#list-templates] ``` GET /api/v1/organization/:orgId/templates ``` **Minimum role:** member Returns all templates belonging to the organization. ### Response [#response] ```json { "templates": [ { "id": "tpl_abc123", "name": "Sales Call Debrief", "description": "Structured summary for sales conversations", "sections": [ { "title": "Key Takeaways", "prompt": "List the main outcomes" }, { "title": "Action Items", "prompt": "Extract follow-up tasks" } ], "created_at": "2026-03-01T09:00:00.000Z", "updated_at": "2026-03-15T14:00:00.000Z" } ] } ``` ## Get Template [#get-template] ``` GET /api/v1/organization/:orgId/templates/:templateId ``` **Minimum role:** member Returns a single template by ID. ### Path Parameters [#path-parameters] | Parameter | Type | Description | | ------------ | ------ | ----------------------- | | `templateId` | string | The template identifier | ### Response [#response-1] ```json { "id": "tpl_abc123", "name": "Sales Call Debrief", "description": "Structured summary for sales conversations", "sections": [ { "title": "Key Takeaways", "prompt": "List the main outcomes" }, { "title": "Action Items", "prompt": "Extract follow-up tasks" } ], "created_at": "2026-03-01T09:00:00.000Z", "updated_at": "2026-03-15T14:00:00.000Z" } ``` ## Create Template [#create-template] ``` POST /api/v1/organization/:orgId/templates ``` **Minimum role:** admin Creates a new organization template. ### Request Body [#request-body] | Field | Type | Required | Description | | ------------------- | --------- | -------- | ------------------------------------------- | | `name` | string | Yes | Template display name | | `description` | string | No | Short description of the template's purpose | | `sections` | object\[] | Yes | Ordered list of template sections | | `sections[].title` | string | Yes | Section heading | | `sections[].prompt` | string | Yes | Instruction for the AI summarizer | ### Example Request [#example-request] ```json { "name": "Sales Call Debrief", "description": "Structured summary for sales conversations", "sections": [ { "title": "Key Takeaways", "prompt": "List the main outcomes" }, { "title": "Action Items", "prompt": "Extract follow-up tasks" }, { "title": "Objections", "prompt": "Summarize any objections raised" } ] } ``` ### Response [#response-2] ```json { "id": "tpl_def456", "name": "Sales Call Debrief", "description": "Structured summary for sales conversations", "sections": [ { "title": "Key Takeaways", "prompt": "List the main outcomes" }, { "title": "Action Items", "prompt": "Extract follow-up tasks" }, { "title": "Objections", "prompt": "Summarize any objections raised" } ], "created_at": "2026-04-10T08:00:00.000Z", "updated_at": "2026-04-10T08:00:00.000Z" } ``` ## Update Template [#update-template] ``` PATCH /api/v1/organization/:orgId/templates/:templateId ``` **Minimum role:** admin Updates an existing template. Only provided fields are changed. ### Path Parameters [#path-parameters-1] | Parameter | Type | Description | | ------------ | ------ | ----------------------- | | `templateId` | string | The template identifier | ### Request Body [#request-body-1] | Field | Type | Required | Description | | ------------- | --------- | -------- | ------------------------------------------------------------- | | `name` | string | No | Updated template name | | `description` | string | No | Updated description | | `sections` | object\[] | No | Replacement sections array (fully replaces existing sections) | ### Example Request [#example-request-1] ```json { "name": "Sales Call Debrief v2" } ``` ### Response [#response-3] ```json { "id": "tpl_abc123", "name": "Sales Call Debrief v2", "description": "Structured summary for sales conversations", "sections": [ { "title": "Key Takeaways", "prompt": "List the main outcomes" }, { "title": "Action Items", "prompt": "Extract follow-up tasks" } ], "created_at": "2026-03-01T09:00:00.000Z", "updated_at": "2026-04-10T09:00:00.000Z" } ``` ## Delete Template [#delete-template] ``` DELETE /api/v1/organization/:orgId/templates/:templateId ``` **Minimum role:** admin Permanently deletes an organization template. Existing summarizations that used this template are not affected. ### Path Parameters [#path-parameters-2] | Parameter | Type | Description | | ------------ | ------ | ----------------------- | | `templateId` | string | The template identifier | ### Response [#response-4] ```json { "success": true } ``` # Organization Users The users endpoint lets organization owners and admins programmatically discover the members of their organization and update each member's personal Pocket configuration — default summary template, AI model, language, notification preferences, encrypted user profile, and learned summarization preferences. Use it to centrally apply opinionated defaults or build custom onboarding flows. These endpoints are available both as part of the Express organization API (`/api/v1/organization/:orgId/users`) and as aliases on the public API host (`/api/v1/public/users`). The public API aliases proxy to the organization API so all encryption, validation, and audit logic lives in one place. ## Authentication [#authentication] All routes accept either authentication mode below. | Auth | Header | Required role/scope | | -------------------- | ------------------------------------------- | --------------------------------------------------------------- | | Firebase ID token | `Authorization: Bearer ` | Active org member with role `owner` or `admin` | | Organization API key | `Authorization: Bearer pk_xxx` | Org key for the same organization with the matching scope below | Personal user API keys (`pk_user_*`) are intentionally rejected on these routes — they are personal credentials and must not be used to administer other members. | Operation | Required org key scope | | --------------------------------- | ---------------------- | | List users / read settings bundle | `users:read` | | Update settings bundle | `users:write` | ## List Users [#list-users] ``` GET /api/v1/organization/:orgId/users GET /api/v1/public/users ``` Returns a paginated list of **active** members of the organization. Pending and removed members are excluded. Results are sorted by email ascending. ### Query Parameters [#query-parameters] | Parameter | Type | Description | | --------- | ------- | ------------------------------------------------------------------ | | `q` | string | Optional case-insensitive substring match on email or display name | | `page` | integer | 1-based page number, default `1` | | `limit` | integer | Items per page (max `100`), default `25` | ### Response [#response] ```json { "success": true, "data": [ { "user_id": "usr_001", "email": "alice@example.com", "display_name": "Alice Liu", "role": "admin", "status": "active", "is_active": true, "created_at": "2025-12-01T18:42:11.000Z", "updated_at": "2026-04-08T10:14:22.000Z", "member_since": "2026-01-04T15:00:00.000Z", "recording_count": 42, "latest_recording_at": "2026-04-29T09:21:33.000Z" } ], "pagination": { "page": 1, "limit": 25, "total": 1, "total_pages": 1, "has_more": false } } ``` ## Get Member Settings [#get-member-settings] ``` GET /api/v1/organization/:orgId/users/:userId/settings GET /api/v1/public/users/:user_id/settings ``` Returns an admin-safe bundle of personal configuration for a single active member. Sensitive sections (`profile`, `preferences`, `tags`) are only included when explicitly requested via the `include` query parameter. ### Query Parameters [#query-parameters-1] | Parameter | Type | Description | | ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `include` | string | Comma-separated list of optional sections: `profile`, `preferences`, `tags`. The notifications block is included by default; pass `none` to omit it. | | `include_profile` | boolean | Alternative per-section flag. Same effect as listing it in `include`. | | `include_preferences` | boolean | Alternative per-section flag. | | `include_tags` | boolean | Alternative per-section flag. | | `include_notifications` | boolean | Alternative per-section flag. Defaults to true. | | `preferences_page` | integer | When `preferences` is included, 1-based page number. Defaults to `1`. | | `preferences_limit` | integer | When `preferences` is included, page size (max `200`). Defaults to `50`. | ### Response [#response-1] ```json { "success": true, "data": { "user": { "user_id": "usr_001", "email": "alice@example.com", "display_name": "Alice Liu", "role": "admin", "status": "active", "timezone": "America/Los_Angeles" }, "settings": { "conversation_language": "English (US)", "selected_theme": "auto_detect", "selected_model": "gemini35Flash", "auto_transcription": true, "sync_to_icloud": true, "auto_add_tasks_from_summaries": true, "auto_route_enabled": false, "calendar_matching": false, "find_pocket_enabled": false, "monthly_transcription_minutes": 300, "created_at": "2026-01-04T15:00:00.000Z", "updated_at": "2026-04-08T10:14:22.000Z" }, "notifications": { "highlight_time": "22:00", "processing_notifications_enabled": true, "sync_nudges_enabled": true, "morning_welcome_notifications_enabled": true, "reminder_notifications_enabled": true }, "profile": { "profile": "...decrypted markdown...", "version": 7 }, "preferences": { "data": [ { "id": "pref_001", "command": "Make summaries more concise", "command_type": "summary_enhance", "preference_content": "User prefers concise summaries with bullet points.", "source_recording_id": null, "source_summarization_id": null, "metadata": { "source": "org_admin_api" }, "created_at": "2026-03-01T10:00:00.000Z", "updated_at": "2026-03-01T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 50, "total": 1, "total_pages": 1, "has_more": false } }, "tags": [ { "id": "tag_001", "name": "1:1s", "color": "#33aaff", "created_at": "...", "updated_at": "..." } ] } } ``` ## Update Member Settings [#update-member-settings] ``` PATCH /api/v1/organization/:orgId/users/:userId/settings PATCH /api/v1/public/users/:user_id/settings ``` Applies an allow-listed subset of changes to the target member. The body may contain any combination of the four sections below; at least one must be supplied. Unknown fields are rejected with `400 INVALID_SETTING`. ### Request Body [#request-body] ```json { "settings": { "selected_theme": "executive_summary", "selected_model": "gemini35Flash", "conversation_language": "English (US)", "auto_transcription": true }, "notifications": { "highlight_time": "22:00", "reminder_notifications_enabled": true }, "profile": { "profile": "Markdown profile that will be encrypted under the target user." }, "preferences": [ { "command": "Add follow-ups", "command_type": "manual", "preference_content": "Always include explicit follow-ups." }, { "id": "pref_005", "preference_content": "Updated wording" }, { "id": "pref_006", "delete": true } ] } ``` ### Behavior Notes [#behavior-notes] * **Settings & notifications** — the listed boolean / string fields are validated and merged. `selected_model` is normalized against the active model list and falls back when unknown. * **Profile** — strings up to 100,000 characters. Stored encrypted under the target user, increments `profile_version`, and writes a new row to `user_profile_versions` with source `org_admin_api`. * **Preferences** — each entry is one of: create (omit `id`), update (`id` + fields), or delete (`id` + `delete: true`). Audit metadata (acting user / org API key id, correlation id, `source: "org_admin_api"`) is merged onto every create/update — even when the entry omits a `metadata` field. The LLM classifier is **not** invoked. * All cross-user mutations are logged with `organization_id`, target user id, the actor, the changed sections, and a correlation id. Profile and preference content are never logged. ### Response [#response-2] ```json { "success": true, "applied": { "settings": true, "notifications": true, "profile": true, "preferences_created": 1, "preferences_updated": 1, "preferences_deleted": 1 }, "profile_version": 8 } ``` ### Errors [#errors] | Status | Code | Reason | | ------ | ------------------------------------------------------------- | --------------------------------------------------------- | | 400 | `EMPTY_PATCH` | No section was provided. | | 400 | `INVALID_SETTING` / `INVALID_PROFILE` / `INVALID_PREFERENCES` | Field-level validation failed. | | 403 | `USER_KEY_NOT_ALLOWED` | Personal user API key was used. | | 403 | `ORG_KEY_ORG_MISMATCH` | Org API key belongs to a different organization. | | 403 | `INSUFFICIENT_SCOPES` | Org API key lacks `users:write` (or `users:read` on GET). | | 404 | `MEMBER_NOT_FOUND` | Target user is not an active member of this organization. | # Create upload URL {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Generate a pre-signed S3 URL for uploading a new recording. User API keys require the recordings:write scope; organization API keys are not allowed for this endpoint. # Get audio download URL {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Generate pre-signed S3 URL for audio download # Get recording details {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Get a single recording with full details # List recordings {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Get paginated list of recordings with optional filtering. Note: All dates are interpreted as UTC. # Search recordings {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Search across recording transcripts, summaries, and action items. # List tags {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Get all tags with usage count # Get an organization member's settings bundle {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Returns user\_settings, notifications, and (when requested via `include`) the encrypted user profile and learned preferences for an active org member. Requires an organization API key with the `users:read` scope. # List organization users {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} List active members of the organization that the calling org API key belongs to. Requires an organization API key with the `users:read` scope. User API keys are rejected. # Patch an organization member's settings bundle {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Updates an allow-listed subset of `settings`, `notifications`, `profile`, and learned `preferences` for the target member. Profile updates are encrypted under the target user and create a new profile version with source `org_admin_api`. Requires an organization API key with the `users:write` scope. # Webhooks Pocket sends webhook notifications to your endpoint when recording events occur. Use webhooks to trigger automations in tools like n8n, Zapier, and Make, or in your own backend. ## Supported Events [#supported-events] ### Processing Events [#processing-events] | Event | Fired When | | -------------------------- | ------------------------------------------------------------------------------ | | `transcription.completed` | Transcript generation is complete | | `summary.completed` | Full post-processing is complete (summary, actions, tags, and related outputs) | | `summary.regenerated` | Full summary package is regenerated | | `summary.updated` | Summary text is regenerated | | `mind_map.completed` | Mind map generation is complete | | `action_items.regenerated` | Action items are regenerated | | `speakers.labeled` | Speaker labels are resolved in the transcript | ### User Actions [#user-actions] | Event | Fired When | | ----------------------- | ---------------------------------------------- | | `transcript.edited` | A user edits transcript text or speaker labels | | `action_items.updated` | A user edits or completes an action item | | `recording.created` | A recording is created or uploaded | | `recording.deleted` | A recording is deleted | | `recording.merged` | Two or more recordings are merged | | `translation.completed` | Transcript translation is complete | ## Setup [#setup] Configure webhook destinations in the Pocket app integrations UI for personal webhooks. Organization owners and admins can additionally configure organization-wide webhooks via the Pocket organization API: | Method | Path | Description | | -------- | ----------------------------------------------- | --------------------------------------------------------- | | `GET` | `/api/v1/organization/:orgId/webhooks` | List org webhook integrations | | `GET` | `/api/v1/organization/:orgId/webhooks/:id` | Fetch a specific org integration | | `POST` | `/api/v1/organization/:orgId/webhooks` | Create an org webhook integration (admin only) | | `PUT` | `/api/v1/organization/:orgId/webhooks/:id` | Update an org webhook integration (admin only) | | `DELETE` | `/api/v1/organization/:orgId/webhooks/:id` | Remove an org webhook integration (admin only) | | `POST` | `/api/v1/organization/:orgId/webhooks/:id/test` | Send a sample payload to verify the endpoint (admin only) | When a recording event fires for a user who belongs to one or more organizations, Pocket delivers the event to that user's personal webhook(s) and to every active organization's webhook(s) in addition. New personal webhooks automatically get a signing secret. Pocket shows the plaintext secret once when the webhook is created, and again only if you rotate it. Store it in your own secret manager before closing the dialog. ## Delivery [#delivery] | Setting | Value | | ------------------ | --------------------------------------- | | HTTP method | POST | | Content-Type | `application/json` | | User-Agent | `HeyPocket-Webhook/1.0` | | Timeout | 30 seconds | | Retries | 3 attempts (exponential backoff 1s–30s) | | Delivery guarantee | At-least-once | ## Payload Structure [#payload-structure] Every payload includes a top-level `user` object identifying the recording owner. Organization-scoped deliveries also include an `organization` object so the receiver knows which org's webhook fired. ```json { "event": "summary.completed", "timestamp": "2026-02-18T12:00:00.000Z", "user": { "id": "user_abc123", "email": "alice@example.com" }, "organization": { "id": "org_def456" }, "recording": { "id": "rec_abc123", "title": "Team Standup", "description": "Weekly sync", "duration": 1800, "language": "English", "recordingAt": "2026-02-17T15:02:00.000Z", "createdAt": "2026-02-18T11:30:00.000Z" }, "summarizations": { "sum_456": { "id": "row_789", "summarizationId": "sum_456", "processingStatus": "completed", "v2": { "summary": { "title": "Team Standup", "emoji": "📋", "markdown": "## Key Decisions\n\n...", "bulletPoints": ["Ship v2 by Friday", "Review design docs"] }, "actionItems": { "version": "3", "actionItems": [ { "id": "subtask_1", "parentTaskId": "task_1", "title": "Ship v2 by Friday", "dueDate": "2026-02-20", "status": "TODO", "globalActionItemId": "gai_001", "isCompleted": false, "is_completed": false } ] }, "mindMap": { "nodes": [], "edges": [] }, "speakerMindMap": null, "clusterMindMap": null, "contextMindMap": null, "flowMindMap": null }, "settings": { "modelId": "gpt5", "themeId": "auto_detect", "language": "English" }, "autoInitiated": true, "createdAt": "2026-02-18T12:00:00.000Z", "updatedAt": "2026-02-18T12:00:05.000Z" } }, "transcript": [ { "speaker": "SPEAKER_00", "speakerName": "Alice", "text": "Let's go over this week's priorities.", "start": 0.0, "end": 3.5 }, { "speaker": "SPEAKER_01", "text": "Sounds good.", "start": 3.5, "end": 4.2 } ], "speakers": { "SPEAKER_00": { "name": "Alice", "speakerId": "spk_abc123" } } } ``` ### Speaker Names [#speaker-names] | Field | Meaning | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transcript[].speaker` | The raw speaker label from the transcript, such as `SPEAKER_00` or `USER_SPEAKER_...`. | | `transcript[].speakerName` | The name shown for that speaker in Pocket. Omitted when the speaker has no name yet. | | `speakers` | Maps each named speaker label to `{ name, speakerId }`. Labels without a name are not listed. Sent only with the transcript, so it is left out when the webhook excludes the transcript. | A speaker's name is shared by every recording they appear in. Renaming or merging a speaker sends a `transcript.edited` webhook for each of those recordings, so every payload carries the updated name. Renaming a speaker for one recording only sends it for that recording. ### Recording Timestamps [#recording-timestamps] | Field | Meaning | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recording.recordingAt` | When the recording started, in UTC (ISO 8601). Pocket device recordings use the device clock, so this stays accurate when the device syncs hours or days after the conversation. Add `recording.duration` (seconds) to get the end time. | | `recording.createdAt` | When the recording was uploaded to Pocket. | | `timestamp` | When this webhook was sent. | Use `recordingAt` rather than the recording title to find when a conversation happened. The default title is a display string in the owner's local time, and it usually changes after processing. ## Signature Verification [#signature-verification] Each personal webhook created in the current app includes HMAC-SHA256 signature headers. Older webhook rows without a secret may continue to send unsigned deliveries until you rotate or recreate the webhook. | Header | Description | | ----------------------- | -------------------------------------------------------- | | `X-HeyPocket-Signature` | HMAC-SHA256 of `{timestamp}.{rawBody}` using your secret | | `X-HeyPocket-Timestamp` | Unix timestamp (ms) of the delivery | Verify each request by computing `HMAC-SHA256(secret, "${timestamp}.${rawBody}")` and comparing it to `X-HeyPocket-Signature`. Use the exact raw JSON request body bytes you received, before parsing or re-serializing. ```javascript const crypto = require('crypto'); function verifySignature(secret, timestamp, body, signature) { const expected = crypto .createHmac('sha256', secret) .update(`${timestamp}.${body}`) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(signature) ); } ``` ## When Webhooks Fire [#when-webhooks-fire] Webhooks fire for processing completion events and user-driven updates (recordings, transcripts, action items, and translations). # Ask Pocket (AI Chat) Ask Pocket is your AI assistant that remembers everything you've said. Instead of listening to a whole recording, just ask for the information you need. ## What you can ask [#what-you-can-ask] * "What were the main objections in today's sales call?" * "Remind me of the project timeline we discussed on Tuesday." * "Summarize jamie's feedback on the new design." Beyond simple Q\&A, Pocket Chat offers powerful ways to slice and dice your data: * **Contextual Suggestions**: Not sure what to ask? Pocket provides suggestions based on your context. * **Conversation Filters**: Target your questions to specific dates or specific recordings to get more precise answers. * **Session History**: Revisit previous chats with Pocket to pick up where you left off. ## Usage and Limits [#usage-and-limits] To ensure high performance for everyone, Pocket Chat includes some usage considerations: * **Message Limits**: Depending on your plan, there may be a limit on the number of messages you can send per session. * **Conversation Limits**: The number of active chat sessions might be limited for free users. * **Token Context**: Very long conversations may reach a token limit, at which point starting a new chat is recommended for the best accuracy. ## Tips for Better Answers [#tips-for-better-answers] * **Be Specific**: Instead of "What happened today?", try "Summarize the project timeline we discussed in the 2 PM meeting." * **Leverage Tags**: If you use labels for your recordings, mention them in your questions (e.g., "What are the action items from all meetings tagged #Product?"). # Speaker Management Pocket automatically detects different speakers in your recordings. **Speaker Management** allows you to turn those generic "Speaker 1" labels into a well-organized library of people. > **Note:** Automatic speaker detection is unavailable for recordings that are three hours or longer because speaker identification becomes unreliable at that length. ## Identification (Tagging) [#identification-tagging] When a new speaker is detected, they appear as an "Untagged Speaker." You can give them a name to make your transcripts and summaries much easier to read. 1. **Open a Recording**: Tap on any transcript where voices were detected. 2. **Tag Speaker**: Tap the speaker label and enter their name. 3. **Global Update**: Once you've named a speaker, Pocket will recognize them across your other recordings. ## Merging Speakers [#merging-speakers] Sometimes the same person might be detected as two different speakers (e.g., if their voice sounds different on a call versus in person). You can merge these profiles: 1. **Access Speaker Management**: Go to **Profile** > **Speaker Management**. 2. **Select Speakers**: Enter selection mode and select the duplicate profiles. 3. **Merge**: Tap **Merge** and choose the primary name to keep. All associated recordings will now be linked to that single speaker. ## Speaker Insights [#speaker-insights] From the **Speaker Management** screen, you can tap on any named speaker to: * **View All Recordings**: See every conversation where this person was a participant. * **Rename**: Update their global display name. * **Delete**: Remove a speaker profile from your library (this resets them to "Untagged" in your transcripts). > Deleting a speaker profile does not delete the recordings themselves; it only removes the naming and organization associated with that person. # Voice Print **Voice Print** is a personalized AI feature that allows Pocket to distinguish your voice from others in a conversation. Once trained, your name will be automatically tagged in transcripts, making summaries and action items even clearer. ## Training Your Voice [#training-your-voice] Setting up your Voice Print takes less than a minute. Pocket will ask you to read a few short sentences to capture the unique characteristics of your voice. 1. **Open Settings**: Go to the **Profile** tab and select **Voice Print**. 2. **Follow Prompts**: Read the text displayed on the screen clearly and at a normal volume. 3. **Completion**: Once the AI has processed your voice, the "User Recognition" feature will be active for all future recordings. ## Benefits [#benefits] * **Automatic Tagging**: Instead of seeing "Speaker 1," you'll see your own name (or "You") in every transcript where you speak. * **Clearer Summaries**: AI can better attribute decisions and action items to the correct person. * **Improved Search**: You can use "Ask Pocket" to find things *you* specifically said during a meeting. ## Management and Privacy [#management-and-privacy] * **Recalibration**: If you find that recognition accuracy has decreased (e.g., if you're using a different microphone or your voice has changed), you can **Regenerate Voice Print** at any time in the settings. * **Security**: Your Voice Print is encrypted and used solely for speaker identification within your own account. It is never shared or used to identify you in other contexts. > For the best results, perform the initial training in a quiet environment using the same device (Pocket or your phone) you plan to record with most often. # Enable File System Access in Brave Pocket Web Sync uses the browser's File System Access API to let you choose the Pocket USB drive and sync recordings from it. Brave keeps this API disabled by default, so Web Sync may show: > Your browser does not support the File System Access API. If you want to use Brave for Pocket Web Sync, enable the Brave flag below and then relaunch the browser. ## Enable the Brave flag [#enable-the-brave-flag] 1. Open a new tab in Brave. 2. Go to `brave://flags/#file-system-access-api`. 3. Set **File System Access API** to **Enabled**. 4. Click **Relaunch** when Brave prompts you to restart. 5. Return to [Pocket Web](https://app.heypocket.com/) and try Web Sync again. ## If Web Sync still does not open the folder picker [#if-web-sync-still-does-not-open-the-folder-picker] * Confirm the page is running in Brave after the relaunch, not in the old browser session. * Open `brave://flags/#file-system-access-api` again and make sure the flag is still **Enabled**. * Disable Brave Shields for `app.heypocket.com` if the folder picker still does not appear. * Make sure you are using a USB-C data cable and that Web Sync is enabled in the Pocket mobile app. If Brave still blocks access, use Chrome or Microsoft Edge for Pocket Web Sync, or use the Pocket desktop app. # Device Management Pocket is designed to work seamlessly with your hardware device. This guide covers the setup process and how to keep your device synced and up-to-date. ## Initial Setup [#initial-setup] When you first open the Pocket app, you'll be guided through the onboarding process: 1. **Bluetooth Pairing**: The app will search for your Pocket device. Ensure Bluetooth is enabled on your phone and your device is powered on. 2. **Permissions**: Pocket requires Bluetooth and Location permissions (on Android) to discover and connect to your device. 3. **Voiceprint**: You may be asked to record a short voice sample to help Pocket identify you in multi-speaker conversations. ## Bluetooth Sync [#bluetooth-sync] Once paired, your device connects automatically whenever it's in range. * **Auto-reconnect**: The app attempts to reconnect in the background if the connection is lost. * **Memory Transfer**: Recordings made on your device are automatically transferred to the app over Bluetooth. * **Status Indicators**: You can see the battery level and connection status of your device directly in the app's home screen. ## Firmware Updates (OTA) [#firmware-updates-ota] We constantly improve Pocket with new features and performance enhancements. * **Automatic Checks**: The app checks for firmware updates periodically. * **Over-the-Air (OTA)**: Updates are delivered wirelessly from your phone to your device. * **WiFi Updates**: Some larger updates might require your device to connect directly to WiFi for faster downloading. ## Troubleshooting [#troubleshooting] If you're having trouble connecting: * Ensure your device is charged and nearby. * Toggle Bluetooth off and on in your phone's settings. * Restart the Pocket app. # Word Dictionary Pocket's AI is powerful, but it might not know every unique name, industry jargon, or brand you use. The **Word Dictionary** allows you to fine-tune transcription accuracy for your specific needs. ## Custom Words [#custom-words] Use **Custom Words** for terms that Pocket should recognize and keep as-is. This is ideal for: * **Personal Names**: Friends, colleagues, or unique surnames. * **Brand Names**: Your company name or specialized products. * **Technical Jargon**: Industry-specific acronyms or niche terminology. > Adding a custom word helps the AI prioritize that specific spelling when it hears a similar-sounding phonetic match. ## Word Corrections [#word-corrections] If Pocket consistently mishears a specific word (e.g., hearing "care-oh" instead of "Karo"), you can add a **Word Correction**. * **Misheard Word**: The incorrect word Pocket usually generates. * **Corrected Word**: The spelling you want it to use instead. Pocket will automatically replace these recurring mistakes in future transcriptions. ## Limitations [#limitations] * **Recording Length**: Dictionary words and corrections are currently applied to recordings **under 1 hour** in length. * **Processing Time**: Updates to your dictionary are applied to *future* recordings and may not retroactively change existing transcripts. # Pocket Web Sync (USB-C) Pocket Web Sync allows you to transfer recordings directly from your Pocket device to your computer using a USB-C cable. This is the fastest way to sync large files and manage your device storage.