> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicmealkits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plaud

> Read your Plaud voice-recorder library — recordings, transcripts, AI summaries, note tabs, devices, and search.

The Plaud group powers the **Plaud (Magic Meal Kits)** Make.com app. It is a facade over
Plaud's web API — mostly reads (recordings, transcripts, summaries, search) plus a set of
writes (rename, trash, tag/organize, and auto transcribe + summarize). Your server holds
your Plaud credentials in Secret Manager, so callers only ever send the MMK `X-API-KEY`
header (see [Authentication](/authentication)).

<Note>
  **Every Plaud endpoint requires a Pro license.** A Basic key is rejected with `400`
  and `you are not a magic meal kits PRO user`.
</Note>

## Endpoints

Every endpoint below is **Pro**-only.

### User & system

| Endpoint                           | What it does                                              |
| ---------------------------------- | --------------------------------------------------------- |
| `GET /plaud/user/me`               | Profile, membership tier, remaining transcription seconds |
| `GET /plaud/user/feature-access`   | Feature-flag payload (loose upstream envelope)            |
| `GET /plaud/doctor`                | Live connectivity health check (`ok`, per-check status)   |
| `GET /plaud/membership/status`     | Membership / free-trial state                             |
| `GET /plaud/config`                | Client config (`config/init`)                             |
| `GET /plaud/combine/running-tasks` | In-flight combine (merge-audio) tasks                     |

### Files

| Endpoint                              | What it does                                                    |
| ------------------------------------- | --------------------------------------------------------------- |
| `GET /plaud/files`                    | List recordings (paginated, sortable)                           |
| `GET /plaud/files/{id}`               | Recording metadata only                                         |
| `PATCH /plaud/files/{id}`             | Rename a recording → `204`                                      |
| `GET /plaud/files/{id}/fetch`         | Bundle: file + transcript + summary + share + audio in one call |
| `GET /plaud/files/{id}/share`         | Private/public share states                                     |
| `POST /plaud/files/{id}/ack-pull`     | Acknowledge device pull → `204`                                 |
| `POST /plaud/files/trash`             | Soft-delete (trash) recordings, recoverable → `204`             |
| `GET /plaud/sync`                     | Aggregate multiple recordings + attachments in one call         |
| `GET /plaud/files/webhook-candidates` | Poll ready-to-ship recordings (new-recording trigger)           |

### Content

| Endpoint                             | What it does                                              |
| ------------------------------------ | --------------------------------------------------------- |
| `GET /plaud/files/{id}/transcript`   | Transcript (optionally rendered to text/markdown/srt/vtt) |
| `GET /plaud/files/{id}/summary`      | AI Markdown summary (images as pre-signed URLs)           |
| `GET /plaud/files/{id}/tabs`         | List named note tabs (Summary, Key Points, …)             |
| `GET /plaud/files/{id}/tabs/content` | One tab's content, by `tab_id` or `template`              |
| `GET /plaud/files/{id}/audio-url`    | Pre-signed S3 URL for the original audio                  |

### Folders (tags)

| Endpoint                        | What it does                                            |
| ------------------------------- | ------------------------------------------------------- |
| `GET /plaud/tags`               | List tags (folders)                                     |
| `POST /plaud/tags`              | Create a tag → returns the new tag id                   |
| `POST /plaud/files/update-tags` | Assign a tag (or clear with empty `filetag_id`) → `204` |
| `POST /plaud/files/organize`    | One-call resolve-or-create tag + assign                 |

### AI (transcribe + summarize)

| Endpoint                                | What it does                                              |
| --------------------------------------- | --------------------------------------------------------- |
| `POST /plaud/files/{id}/transsumm`      | Start transcribe + summarize (async) — `402` on low quota |
| `POST /plaud/files/{id}/transsumm/wait` | Trigger, poll to completion, return the bundle            |
| `GET /plaud/ai/status`                  | AI task status for `file_ids` (comma-separated)           |
| `GET /plaud/ai/trans-status`            | Total / remaining transcription seconds                   |
| `GET /plaud/user/transcription-quota`   | `is_starter` / `usage_reached` flags                      |
| `GET /plaud/summary/models`             | LLM models available for summaries                        |

### Search

| Endpoint                    | What it does                        |
| --------------------------- | ----------------------------------- |
| `GET /plaud/search`         | Full-text search across transcripts |
| `GET /plaud/search/history` | Recent search queries               |

### Devices & webhooks

| Endpoint                          | What it does                                       |
| --------------------------------- | -------------------------------------------------- |
| `GET /plaud/devices`              | Bound Plaud hardware                               |
| `POST /plaud/files/{id}/dispatch` | POST a recording's payload to a caller webhook URL |

## Triggers

The **Watch New Note** instant trigger in the Make app is delivered by your server's
webhook orchestrator — it is not an endpoint you call. The **Watch New Recordings**
polling trigger reads `GET /plaud/files/webhook-candidates`, which returns only
recordings that are ready (not trashed, transcribed, and summarized).

## Notes

* **Readiness.** Use the `is_trans` / `is_summary` flags (on file objects) or the
  `409` not-ready response to skip recordings whose transcript/summary is still
  generating.
* **Pre-signed URLs expire.** Audio URLs and summary image URLs are short-lived S3 links
  (\~15 minutes) — fetch and use them promptly.
* **One bundle call.** Prefer `/files/{id}/fetch?include=transcript,summary` over three
  separate round trips when you need multiple attachments for the same recording.
* **Reconnect on `401`.** A `401` means your stored Plaud credentials were rejected
  (revoked/expired) — reconnect your Plaud account on the Magic Meal Kits app.

Use the interactive playground on each endpoint page to try a request with your own
deployment host and API key.