# Monologue Docs
> Guides for the Monologue apps, Public API, and private Enterprise API.
# App guides
Source: https://www.monologue.to/docs
Monologue lets you speak anywhere you would normally type. Start a dictation, say what you mean, and Monologue turns it into clean text in the app you are using.
Install Monologue, grant permissions, and try your first dictation.
Enable the Monologue keyboard and start dictating in other apps.
Capture meetings and ideas, then work with transcripts, summaries, speakers, and tags.
Search, edit, organize, and share your synced Voice Notes from a browser.
Teach Monologue names and terminology, then tailor the writing style with modes and
instructions.
Restore recording, pasting, keyboard access, language selection, or connectivity.
## Popular guides
- [Choose or change your shortcut](/dictation/shortcuts)
- [Choose a microphone](/dictation/microphones-and-audio)
- [Change languages or processing models](/dictation/languages-and-models)
- [Use Australian or British English spelling](/personalize/australian-or-british-english)
- [Set up the iPhone Action Button](/iphone-and-ipad/action-button-and-shortcuts)
- [Find and recover recent transcripts](/dictation/history)
- [Connect an AI agent to Voice Notes](/integrations/mcp)
- [Manage your account and subscription](/account-and-privacy/account-and-billing)
- [Fix recording or pasting problems](/troubleshooting/dictation-and-pasting)
## Need a person?
Email [support@monologue.to](mailto:support@monologue.to), or read [how to report a problem](/support/contact-support) so we have the details needed to help quickly.
---
# Account and billing
Source: https://www.monologue.to/docs/account-and-privacy/account-and-billing
## Check your current access
On Mac, open **Settings → Plan & Billing**. On iPhone or iPad, open **Settings → Subscription**. The app shows the access currently attached to your signed-in Monologue account.
| Access shown | What it means |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| Free | You are using Monologue without an active paid entitlement. The app shows any current usage allowance. |
| Pro | You have an individual paid subscription. |
| Every Bundle | Your Monologue access comes from an eligible Every subscription. |
| Team | Your organization gives you Pro access. |
Plan availability and limits can change. Use the plan screen in the app as the source of truth for your account.
## Manage or cancel a subscription
Where you manage billing depends on the purchase source shown in the app:
- **Apple App Store:** Select **Manage** in the iPhone or iPad app, or open your Apple subscriptions. Apple handles the charge, receipt, cancellation, and refund request.
- **Direct Monologue purchase:** Select **Manage subscription** in **Plan & Billing** to open the billing portal.
- **Every Bundle:** Select **Manage subscription** to open your Every account.
- **Team:** A team admin manages billing. Members should contact their admin; admins can open the team billing page from **Plan & Billing**.
Canceling one purchase source does not automatically cancel another. If you see more than one charge, first confirm the Apple ID, Monologue account email, and receipt associated with each purchase.
## Changing plans or purchase sources
Review the price, renewal date, and effective date shown by Apple or in the billing portal before confirming a change. Do not assume unused time, credits, or refunds will transfer between Apple, Monologue, Every, or a team plan.
If you need to move between purchase sources or think the wrong account was charged, [contact support](/support/contact-support) before buying again. Include the Monologue account email and the purchase source, but do not send a full card number, password, or verification code.
---
# Permissions and privacy
Source: https://www.monologue.to/docs/account-and-privacy/permissions-and-privacy
Monologue asks only for permissions needed by the features you use.
| Permission | Why it is used |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Microphone | Records your voice for dictation and Voice Notes. |
| Accessibility (Mac) | Detects global shortcuts and inserts text into other apps. |
| Screen capture (Mac, optional) | Lets Deep context use supported on-screen content to improve a result. |
| Full Access (iPhone and iPad keyboard) | Lets the keyboard exchange the information needed for dictation with the Monologue app and services. |
You can review or revoke system permissions at any time. Features that depend on a revoked permission will stop working until it is restored.
## Review permissions on Mac
Open **System Settings → Privacy & Security**, then select **Microphone**, **Accessibility**, or **Screen & System Audio Recording**. The last label can differ on older macOS versions.
After changing Microphone or Accessibility access, quit and reopen Monologue. Screen capture is optional: leave it off if you do not want to use Deep context.
## Review permissions on iPhone or iPad
- Open **Settings → Privacy & Security → Microphone** to review microphone access.
- Open **Settings → General → Keyboard → Keyboards → Monologue** to review **Allow Full Access**.
- Open the Monologue app and go to **Settings → Preferences** to review keyboard-dictation and Live Activity options.
Apple restricts third-party keyboards in password, payment, and some other secure fields. Monologue may not appear in those fields even when permissions are correct.
## Local and online processing
With a local transcription model on Mac, speech-to-text can run on your Mac and work offline. Smart formatting still requires an internet connection. Remote transcription and iPhone or iPad dictation send the audio and relevant context to Monologue's services for processing.
Send only the context that helps with the result. Do not dictate passwords, authentication codes, API keys, or other secrets.
## Data controls
Open **Settings → Data & Privacy** in the Mac, iPhone, or iPad app. From there you can:
- Delete dictation transcripts and related local data stored on that device.
- Choose whether to share dictation transcripts with Monologue to improve dictation quality.
- Review links to the current terms and privacy policy.
On Mac, this screen also controls optional Deep context and its screen-capture permission.
Deleting local transcripts is different from deleting your Monologue account. For an account deletion or privacy request that the app does not offer, [contact support](/support/contact-support).
---
# Sign in and account recovery
Source: https://www.monologue.to/docs/account-and-privacy/sign-in-and-account-recovery
## Use Monologue on another device
Sign in with the same account on each device. The safest option is to use the same sign-in button you used originally: email, Google, Apple, or Every.
After signing in, check the email shown under **Settings → Account** and confirm the expected plan appears under **Plan & Billing** on Mac or **Subscription** on iPhone and iPad.
## Sign in with Apple and Hide My Email
If you chose **Hide My Email**, Apple gives Monologue an address ending in `@privaterelay.appleid.com`. That relay address can be different from your usual email and may create or open a different Monologue account.
If your plan or history looks missing:
1. Do not purchase a second subscription.
2. Check the email shown in **Settings → Account**.
3. In your Apple ID settings, review the address used for Monologue under **Sign in with Apple**.
4. Sign out, then use the same Apple account and choice you used originally.
If two Monologue accounts already exist, [contact support](/support/contact-support) with both account emails. Do not send an Apple password or verification code.
## Every access is missing
Every access is matched to the identity returned by your Every account. If Monologue shows Free or a different paid source:
1. Check the Monologue account email under **Settings → Account**.
2. Sign out of Monologue.
3. Select **Continue with Every** and finish sign-in with the Every account that holds the subscription.
4. Reopen **Plan & Billing** or **Subscription** and check for **Every Bundle**.
An Apple relay address, an old email, or a different Every login can point to another Monologue account. If access is still missing, contact support with the Monologue email, Every account email, device, and approximate time of the sign-in attempt.
## Change your email
On Mac, open **Settings → Account → Change email**, enter the new address, then enter the six-digit code sent to that address.
Self-serve email changes are not currently available for an account with active Every Bundle access. If the app blocks the change, or if you only use iPhone or iPad, [contact support](/support/contact-support).
## Recover access
- **Email sign-in:** Request a new sign-in code and check spam or filtered folders. Use only the newest code you requested.
- **Google, Apple, or Every:** Recover access with that provider first, then return to Monologue and use the same sign-in button.
- **No access to the account email or provider:** Contact support with the email shown on the account, purchase source, device, and any receipt identifier you can safely share.
Support will never need your password, full payment-card number, or one-time verification code.
## Delete your account
On iPhone or iPad, open **Settings → Account → Delete Account** and follow the confirmation flow. Account deletion is permanent, so export anything you need first. If you use only the Mac app, [contact support](/support/contact-support) for help deleting the account.
---
# History and recent transcripts
Source: https://www.monologue.to/docs/dictation/history
The Mac app keeps recent dictations in History. Use it when a paste went to the wrong app, you need an earlier result, or you want to report a quality problem.
Open **Home** in Monologue and find the dictation in your recent history. From a transcript you can:
- Copy the result.
- Play the source audio when it is available.
- Retry processing after a recoverable failure.
- Delete the transcript.
- Reveal a related local file in Finder when that option is available.
- Send positive or negative feedback.
The Home view also shows recent activity for quick access.
## Paste the latest result again
Use **Paste last transcript** from the Monologue menu bar, or configure its shortcut under **Settings → Dictation**. It inserts the most recent dictation into the active app without replacing the other content already on your clipboard.
## When pasting fails
Use **Paste last transcript**, or open History and copy the result manually. If Monologue displays **Copied** or **App changed**, it preserved the result on the clipboard because it could not safely paste into the original text field.
For repeated paste failures, see [Fix dictation and pasting](/troubleshooting/dictation-and-pasting).
---
# Languages and processing models
Source: https://www.monologue.to/docs/dictation/languages-and-models
## Recording languages
On Mac, open **Settings → Dictation → Recording languages**. On iPhone or iPad, open **Settings → Preferences → Languages**.
- Choose **Auto Detect** as the recommended starting point, or select up to three languages you regularly speak.
- If detection chooses the wrong language, select only the languages you regularly speak instead of using Auto Detect.
- If you switch languages in one sentence, include both languages in the selection.
If a result contains unrelated words after you stop speaking, check the microphone for background noise and choose your language explicitly before trying again.
## Remote processing
Remote transcription is the recommended default and generally provides the best accuracy. Audio is sent to Monologue's processing service for transcription and smart formatting.
## Local processing on Apple silicon Mac
Local mode transcribes the raw audio on your Mac and can produce a raw transcript without a network connection. Its accuracy may be lower than remote transcription.
Smart cleanup and context-aware formatting still use Monologue's online service. Without a network connection, the local model can produce raw transcription but not the same polished result you receive from smart formatting.
:::warning[Local does not mean every step is offline]
The speech-to-text step runs locally. Smart formatting may still require a network connection. Choose the mode based on both privacy needs and the result you expect.
:::
## Download the local model
Select **Local** under **Settings → Dictation → Transcription source**, then download the model when prompted. Keep the app open until the status shows that the model is installed. You can delete the model from the same control when you no longer need it.
The model's storage location is managed by Monologue's transcription library and may change between releases. Download it from the app rather than copying files into a hard-coded folder from an older guide.
If a language is repeatedly wrong, report the affected transcript with the in-app `👎` action so support can inspect the exact example.
---
# Mac indicators and system behavior
Source: https://www.monologue.to/docs/dictation/mac-preferences
Monologue can stay quiet in the background or remain visible while you work. These preferences do not change the words in a dictation.
## Choose a recording indicator
Open **Settings → Dictation → Indicator** and choose:
- **Classic** for the full recording indicator at the screen edge.
- **Mini** for a compact indicator near the current text context.
- **None** to hide the visual indicator.
Classic and Mini can remain visible while idle or appear only during recording and processing. Mini can also stay hidden in selected apps.
## Change system behavior
Open **Settings → System** to control:
- **Open on login:** Starts Monologue when you sign in to your Mac.
- **Prevent sleep:** Keeps the Mac awake during a recording.
- **Show dock icon:** Makes Monologue available in the Dock as well as the menu bar.
- **Creator mode:** Keeps the “Dictated with monologue.to” attribution visible.
- **Support non-standard keyboards:** Uses a compatibility paste method for layouts or apps that do not work with ordinary insertion.
Enable **Prevent sleep** before long hands-free dictations or Voice Notes when the Mac may otherwise sleep.
## Fix a compatibility problem
If dictation succeeds but text does not appear, first follow [Dictation or pasting is not working](/troubleshooting/dictation-and-pasting). Try **Support non-standard keyboards** only when your keyboard layout or target app still blocks normal pasting, because compatibility mode uses a different insertion path.
---
# Microphones and audio
Source: https://www.monologue.to/docs/dictation/microphones-and-audio
Monologue can automatically choose an available microphone or follow the device priority you set. A clear input signal matters more than microphone brand or price.
## Choose a microphone on Mac
Open **Monologue → Settings → Mic & Audio**, then choose **Change microphone**. You can let Monologue select a microphone automatically or arrange connected microphones in priority order. The live level meter shows whether the selected microphone can hear you.
When testing a new device:
1. Connect it before starting dictation.
2. Speak normally and confirm that the level meter moves.
3. Record a short test in a plain text field.
If the meter does not move, confirm that Monologue has microphone permission under **System Settings → Privacy & Security → Microphone**. Then reconnect the device or choose another microphone.
## Bluetooth and AirPods
Bluetooth microphones may take a moment to switch into recording mode. If the beginning of speech is missing, connect the device before starting and wait for the recording indicator before speaking.
If quality suddenly drops:
- Reconnect the device.
- Check whether another call or audio app is using the microphone.
- Try the built-in microphone to separate a device problem from a Monologue problem.
Bluetooth headsets often change audio profiles while their microphone is active. If music quality drops during dictation, prefer the Mac's built-in microphone while keeping the headset as the audio output.
## Audio preferences
On Mac, **Settings → Mic & Audio** includes:
- **Sound effects:** Play a sound when dictation starts or stops.
- **Music and videos:** Keep other audio playing, mute it temporarily, or pause and resume it. You can also customize this behavior for individual audio outputs.
On iPhone and iPad, open **Settings → Preferences** to choose whether keyboard dictation uses the device microphone and whether other audio pauses while you dictate.
If Monologue cannot hear any device, follow [Fix dictation and pasting](/troubleshooting/dictation-and-pasting).
---
# Shortcuts and hands-free dictation
Source: https://www.monologue.to/docs/dictation/shortcuts
Open **Monologue → Settings → Dictation** to configure shortcuts that work with your keyboard and other apps.
## Push to talk
Hold a push-to-talk shortcut while speaking, then release it to finish. The default is the right-side Option key. You can add another binding or record a different modifier, key combination, function key, or supported mouse button.
Monologue distinguishes the left and right versions of modifier keys. If you assign right Option, pressing left Option should keep its normal behavior.
## Hands-free dictation
Tap a hands-free shortcut once to start recording, then tap it again to finish. Hands-free bindings are configured separately from push to talk and can use keyboard shortcuts or supported mouse buttons.
## Other useful shortcuts
- **Cancel dictation:** Stops the active recording without inserting a result.
- **Mode picker:** While dictating, tap right Shift to choose Default, Blazing Fast, or one of your modes.
- **Paste last transcript:** Inserts the most recent result again while preserving what was already on your clipboard.
- **Voice Notes shortcuts:** Start, pause, resume, or stop a longer note recording from the Notes settings.
## Avoid shortcut conflicts
If another app already uses your shortcut, only one app may receive it. Right Option can conflict with AI apps such as Claude, keyboard remappers, and layouts that use Option to type special characters.
Change either the other app's shortcut or Monologue's binding under **Settings → Dictation**. A multi-key combination or unused mouse button is usually a safer alternative. If one side of a modifier is needed by your keyboard layout, assign the other side or a different combination.
After changing a shortcut, test push to talk and hands-free dictation separately in a plain text field such as TextEdit or Notes.
---
# Enterprise API
Source: https://www.monologue.to/docs/enterprise-api
:::warning[Private beta]
The Enterprise API is available only to approved organizations. Access is not self-serve, and credentials are provisioned directly by Monologue during onboarding.
:::
Use the Enterprise API when your product needs Monologue's dictation pipeline rather than access to an individual user's Voice Notes.
The guides explain authentication and integration patterns. The endpoint reference lists the exact fields, schemas, and generated request examples.
Upload audio or format existing text in one HTTPS request.
Stream PCM audio over WebSocket for live transcription and formatting.
Submit thumbs-up or thumbs-down feedback for a completed dictation.
Check exact batch and client-token request and response schemas.
If your organization has been invited to the private beta, begin with the [quickstart](/enterprise-api/quickstart). For access or onboarding questions, email [support@monologue.to](mailto:support@monologue.to).
---
# Enterprise API authentication
Source: https://www.monologue.to/docs/enterprise-api/authentication
Send exactly one supported credential per request.
| Credential | Intended use | Authentication |
| ------------------ | ----------------------------------- | ------------------------------------------ |
| Enterprise API key | Trusted servers | `X-API-Key: mlg_ent_live_...` |
| Client token | Browser, mobile, or desktop clients | `Authorization: Bearer mlg_ent_client_...` |
## Server-to-server requests
Keep the provisioned API key in your server's secret manager and pass it in `X-API-Key`. A normal server request should not send an `Origin` header; if it does, the origin must be allowed for that key.
## Client applications
Never ship the long-lived key to a client. Your trusted server should mint a short-lived token and return only that token to the authenticated application.
```bash
curl --request POST \
--url https://api.monologue.to/v1/enterprise/client-tokens \
--header "Content-Type: application/json" \
--header "X-API-Key: $MONOLOGUE_ENTERPRISE_API_KEY" \
--data '{
"origin": "https://app.example.com",
"client_user_id": "user_123",
"client_session_id": "session_456",
"ttl_seconds": 60
}'
```
```json
{
"client_token": "mlg_ent_client_...",
"expires_at": "2026-07-20T10:31:00Z"
}
```
Tokens default to 60 seconds and are capped at 120 seconds. Bind each token to an exact browser `origin` or a stable native `client_app_id`. When a browser sends the request, its actual `Origin` header must match the token.
:::danger[Keep the Enterprise API key server-side]
Calling the token endpoint from a browser with the long-lived API key exposes the key and defeats the client-token design.
:::
---
# Batch dictation
Source: https://www.monologue.to/docs/enterprise-api/batch-dictation
Send `multipart/form-data` to:
```text
POST https://go.monologue.to/v1/enterprise/dictate
```
| `source` | Required input | Result |
| --------------- | -------------- | ------------------------------------------- |
| `smart` | `audio` | Raw transcript and formatted text. |
| `transcription` | `audio` | Raw speech-to-text. |
| `format` | `raw_text` | Formatted text without audio transcription. |
Use `smart` as the default for user-facing dictation.
## Format existing text
```bash
curl --request POST \
--url https://go.monologue.to/v1/enterprise/dictate \
--header "X-API-Key: $MONOLOGUE_ENTERPRISE_API_KEY" \
--form source=format \
--form 'raw_text=can you send avery the launch update' \
--form 'dictionary=Avery' \
--form 'extra_instructions=Write a complete professional sentence.'
```
## Optional fields
- `language`: a code returned by the public [`GET /v1/languages` endpoint](/enterprise-api/reference/languages/listlanguages); omit for automatic detection.
- `context`: current app, surrounding text, or other situation-specific context.
- `dictionary`: names, terminology, acronyms, or preferred replacements.
- `extra_instructions`: request-specific style and formatting behavior.
- `transcription_id`: your correlation ID for diagnostics.
- `platform` and `app_version`: client metadata for support and usage analysis.
- `audio_duration`: client-measured duration hint.
- `store`: explicitly opt into request, response, and audio persistence.
Audio uploads are limited to 100 MB by default. See [limits and errors](/enterprise-api/limits-and-errors) before implementing retries.
Keep the response `id` with the displayed result. It is the transcription ID
used to submit [thumbs-up or thumbs-down feedback](/enterprise-api/feedback).
---
# Data handling
Source: https://www.monologue.to/docs/enterprise-api/data-handling
By default, Enterprise API telemetry is metadata-only. Standard telemetry does not include request or response content, cleaned context, or source audio.
Set `store` to `true` only when your product intentionally opts into request,
response, and audio persistence:
- For [batch dictation](/enterprise-api/batch-dictation), send `store=true` as a multipart form field.
- For [realtime streaming](/enterprise-api/realtime-streaming), send `"store": true` in the initial `session.start` message.
Stored realtime sessions include the streamed audio, raw and final transcripts,
context, dictionary, and extra instructions. Realtime PCM audio is retained as a
mono 16 kHz WAV file. Your enterprise agreement may define additional handling
or retention requirements.
Submitting [transcription feedback](/enterprise-api/feedback) does not
retroactively enable full dictation storage. The feedback signal and
identifiers are stored, plus only the optional text or audio that the client
explicitly attaches.
## Send the minimum useful context
- Prefer cursor-adjacent text over an entire document.
- Include the current app, window title, or selection only when it helps the result.
- Put names and terminology in `dictionary`.
- Put tone and output behavior in `extra_instructions`.
- Remove passwords, API keys, authentication codes, payment details, and unrelated private content.
## Correlate without embedding private data
Use `transcription_id`, `platform`, and `app_version` for diagnostics. Do not put user IDs or internal identifiers into `context` unless the model genuinely needs them to produce the requested output.
Before production, document your own consent, retention, deletion, and access-control behavior for end users. Contact your Monologue representative when contractual requirements differ from the defaults described here.
---
# Transcription feedback
Source: https://www.monologue.to/docs/enterprise-api/feedback
Every batch dictation response includes an `id`. Keep that value with the
result so your product can submit feedback for the exact dictation.
## Submit feedback
Send feedback to:
```text
POST https://go.monologue.to/v1/enterprise/transcriptions/{transcription_id}/feedback
```
Use the same [enterprise authentication](/enterprise-api/authentication) as the
dictation request and send `multipart/form-data`.
| Field | Required | Description |
| ----------- | -------- | --------------------------------------------- |
| `sentiment` | Yes | Exactly `like` or `dislike`. |
| `text` | No | The final text shown to the user, up to 1 MB. |
| `audio` | No | The audio for this dictation, up to 100 MB. |
Thumb-only feedback is valid and is the recommended default:
```bash
curl --request POST \
--url https://go.monologue.to/v1/enterprise/transcriptions/TRANSCRIPTION_ID/feedback \
--header "X-API-Key: $MONOLOGUE_ENTERPRISE_API_KEY" \
--form "sentiment=dislike"
```
When the user has consented to share the example for quality review and model
improvement, attach the final text, audio, or both:
```bash
curl --request POST \
--url https://go.monologue.to/v1/enterprise/transcriptions/TRANSCRIPTION_ID/feedback \
--header "X-API-Key: $MONOLOGUE_ENTERPRISE_API_KEY" \
--form "sentiment=dislike" \
--form "text=The final text shown to the user" \
--form "audio=@dictation.m4a"
```
The API returns `201 Created` after storing the feedback:
```json
{
"feedback_id": "0f85a9bf-3a70-4f21-a752-bf85020f3945",
"transcription_id": "TRANSCRIPTION_ID",
"sentiment": "dislike"
}
```
## Keep the client contract small
Do not resend timestamps, platform, app version, duration, raw text, context,
dictionary, instructions, or custom metadata. Monologue joins the feedback to
existing usage metadata through the transcription ID.
Dictation is still metadata-only by default. A feedback submission always
stores its thumb and identifiers. Optional text or audio is stored only when
your client explicitly attaches it.
Client tokens work for browser, mobile, and desktop feedback requests. Never
embed a long-lived enterprise API key in a client application.
---
# Limits and errors
Source: https://www.monologue.to/docs/enterprise-api/limits-and-errors
Default limits may be adjusted for an approved organization during onboarding.
| Limit | Default |
| --------------------------- | ---------------------------------- |
| Batch requests | 60 requests per minute per account |
| Batch audio upload | 100 MB |
| Concurrent realtime streams | 5 per account |
| Realtime session duration | 10 minutes |
| Realtime context | 128 KB |
## Batch errors
Errors include a machine-readable `code` and human-readable `error` message.
```json
{
"error": "Request body too large",
"code": "REQUEST_TOO_LARGE"
}
```
| Status | Example code | Handling |
| ------ | ------------------------------------------------------ | --------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Correct the request; do not retry unchanged. |
| `401` | Authentication error | Supply exactly one valid credential. |
| `403` | Origin not allowed | Correct the origin or token binding. |
| `408` | `REQUEST_CANCELLED` | Retry with bounded exponential backoff. |
| `413` | `REQUEST_TOO_LARGE` | Reduce the upload size. |
| `429` | Rate limited | Wait for `Retry-After`, then retry. |
| `500` | `PROCESSING_FAILED` | Do not retry indefinitely; contact support if persistent. |
| `503` | `TRANSCRIPTION_TIMEOUT` or `TRANSCRIPTION_UNAVAILABLE` | Retry with backoff and jitter. |
| `504` | `UPSTREAM_TIMEOUT` | Retry with backoff and jitter. |
The `X-Dictate-Attempts` response header reports how many processing attempts were used. Preserve `transcription_id` across a retry so Monologue can correlate the requests.
## Realtime errors
Realtime failures arrive as `session.error`:
```json
{
"type": "session.error",
"code": "...",
"message": "...",
"retry_via_async": true
}
```
When `retry_via_async` is true, close the stream and submit the buffered audio to the batch endpoint. Do not automatically replay audio unless your product can prevent duplicate output and the user still expects the result.
---
# Enterprise API quickstart
Source: https://www.monologue.to/docs/enterprise-api/quickstart
## 1. Store your Enterprise API key
Monologue provides a long-lived key to approved organizations during onboarding. Store it in a server-side secret manager and expose it to your application as an environment variable:
```bash
export MONOLOGUE_ENTERPRISE_API_KEY="mlg_ent_live_..."
```
Never embed this key in a browser, mobile app, desktop app, source repository, or support message. Client applications must use [short-lived client tokens](/enterprise-api/authentication).
## 2. Send an audio file
```bash
curl --request POST \
--url https://go.monologue.to/v1/enterprise/dictate \
--header "X-API-Key: $MONOLOGUE_ENTERPRISE_API_KEY" \
--form source=smart \
--form audio=@recording.m4a \
--form language=en \
--form platform=server
```
```json
{
"id": "ce95ce43-81c5-4dc8-9d31-6f08f0999198",
"text": "Please send the launch update to Avery.",
"raw_text": "please send the launch update to avery"
}
```
## 3. Add relevant context
```bash
curl --request POST \
--url https://go.monologue.to/v1/enterprise/dictate \
--header "X-API-Key: $MONOLOGUE_ENTERPRISE_API_KEY" \
--form source=smart \
--form audio=@recording.m4a \
--form 'dictionary=Monologue, Avery, Every' \
--form 'context=SlackQuick update:' \
--form 'extra_instructions=Write a concise, casual Slack message.'
```
Use `dictionary` for names and terminology, `context` for the current surface and nearby text, and `extra_instructions` for output behavior. Send only what is relevant to this result.
---
# Realtime streaming
Source: https://www.monologue.to/docs/enterprise-api/realtime-streaming
Connect to:
```text
wss://go.monologue.to/v1/enterprise/streaming
```
Use the `monologue.dictate.realtime.v1` protocol. Realtime sessions accept mono 16 kHz signed 16-bit little-endian PCM (`pcm_s16le`) and support `smart` or `transcription` as the source.
## Authenticate
Non-browser clients can send `X-API-Key` or an `Authorization: Bearer` client token during the WebSocket handshake.
Browsers cannot set those headers. Mint an origin-bound [client token](/enterprise-api/authentication), encode it as unpadded base64url, and send it as a credential subprotocol:
```js
const credential = btoa(clientToken).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
const socket = new WebSocket("wss://go.monologue.to/v1/enterprise/streaming", [
"monologue.dictate.realtime.v1",
`monologue.enterprise.bearer.${credential}`,
]);
```
## Start the session
Send `session.start` before any audio. `transcription_id` must be nonblank.
```json
{
"type": "session.start",
"protocol_version": 1,
"transcription_id": "0198b68f-c6e1-7891-a341-803eb8fe421f",
"source": "smart",
"languages": ["en"],
"platform": "web",
"app_version": "1.0.0",
"audio": {
"encoding": "pcm_s16le",
"sample_rate_hz": 16000,
"channels": 1
},
"dictionary": "Monologue, Avery",
"context": "Slack"
}
```
Wait for `session.ready`, then send raw PCM bytes as binary WebSocket frames. Do not wrap them in JSON or base64. When audio is complete, send:
```json
{
"type": "input.commit",
"extra_instructions": "Write a concise Slack message."
}
```
### Optional persistence
Realtime sessions are metadata-only by default. To intentionally persist the
session for diagnostics or feedback, add `"store": true` to the initial
`session.start` message:
```json
{
"type": "session.start",
"protocol_version": 1,
"transcription_id": "0198b68f-c6e1-7891-a341-803eb8fe421f",
"source": "smart",
"store": true,
"audio": {
"encoding": "pcm_s16le",
"sample_rate_hz": 16000,
"channels": 1
}
}
```
This stores the streamed audio, raw and final transcripts, context, dictionary,
and extra instructions associated with the session. Streamed PCM is retained as
a mono 16 kHz WAV file. Set `store` only when your product and end user have
intentionally opted into content persistence. The setting cannot be changed
after the session starts.
Use the same `transcription_id` when submitting [feedback](/enterprise-api/feedback)
so Monologue can correlate the feedback with the stored session data.
## Server events
| Event | Meaning |
| -------------------- | --------------------------------------------------------- |
| `session.ready` | The server is ready for audio. |
| `transcript.partial` | Unstable partial text for live UI. |
| `transcript.segment` | A stable segment and accumulated text. |
| `transcript.final` | Final raw transcript after commit. |
| `result.final` | Final `text`, `raw_text`, output mode, and timing data. |
| `session.completed` | The session finished successfully or was cancelled. |
| `session.error` | The session failed; inspect `code` and `retry_via_async`. |
You may send `context.update` before commit to replace context, dictionary, or extra instructions. Send `session.cancel` to stop without a final result. Audio frames are rejected after `input.commit`.
---
# Monologue Enterprise API
Source: https://www.monologue.to/docs/enterprise-api/reference
Private-beta APIs for approved organizations integrating batch or realtime dictation.
## Dictation
Transcribe audio and format text.
## Feedback
Submit a quality signal for a completed dictation.
## Authentication
Mint short-lived credentials for client applications.
## Languages
Discover the language codes supported by Monologue dictation.
---
# Create a client token
Source: https://www.monologue.to/docs/enterprise-api/reference/authentication/createclienttoken
Mint a short-lived token for a browser, mobile, or desktop client. Call this endpoint only from a trusted server.
---
# Create a dictation
Source: https://www.monologue.to/docs/enterprise-api/reference/dictation/dictate
Transcribe audio, format raw text, or perform both operations in one multipart request.
---
# Submit transcription feedback
Source: https://www.monologue.to/docs/enterprise-api/reference/feedback/submitenterprisefeedback
Attach a thumbs-up or thumbs-down to a completed enterprise dictation. Text and audio are optional evidence stored only when explicitly attached.
---
# List supported languages
Source: https://www.monologue.to/docs/enterprise-api/reference/languages/listlanguages
Return the canonical list of language codes supported by Monologue dictation. Use a returned `code` as the `language` field on dictation requests, or omit `language` to use automatic detection. The list is public and does not require authentication.
---
# Your first dictation
Source: https://www.monologue.to/docs/getting-started/first-dictation
You do not need to speak in commands. Say the thought the way you would explain it to another person, and Monologue cleans up punctuation, casing, filler words, and false starts according to your selected mode.
## On Mac
1. Put the cursor in a text field.
2. Hold your primary shortcut while you speak.
3. Release it when you finish.
4. Keep the target app active until Monologue pastes the result.
For longer thoughts, tap your configured hands-free shortcut once to start and again to finish. Press your configured cancel shortcut if you want to discard the recording.
## On iPhone or iPad
1. Switch to the Monologue keyboard.
2. Tap the microphone.
3. Speak, then stop the recording.
4. The text is inserted at the cursor.
## Get a better result
- Speak in complete thoughts, but do not worry about perfect phrasing.
- Add names, acronyms, and product terms to your [dictionary](/personalize/dictionary).
- Select only the [languages](/dictation/languages-and-models) you actually speak, or choose **Auto Detect**.
- Use [modes and instructions](/personalize/modes-and-instructions) when the output needs a particular tone or structure.
Your recent results remain available in [History](/dictation/history), so a failed paste does not mean the transcript is lost.
---
# Set up Monologue on iPhone or iPad
Source: https://www.monologue.to/docs/getting-started/iphone-and-ipad
Monologue works as a custom keyboard on iPhone and iPad. Setup has two parts: enable the keyboard in iOS Settings, then allow the permissions used for dictation.
## Enable the keyboard
1. Open the Monologue app and complete onboarding.
2. Open **Settings → General → Keyboard → Keyboards**.
3. Tap **Add New Keyboard**, then select **Monologue**.
4. Tap **Monologue** in the keyboard list and turn on **Allow Full Access**.
Full Access lets the keyboard process dictation while you are typing in another app. iOS shows the same general warning for every third-party keyboard; Monologue uses this access for the features you choose to use.
## Allow microphone access
Return to the Monologue app and allow microphone access when prompted. If it was previously denied, open **Settings → Privacy & Security → Microphone** and enable Monologue.
## Switch to Monologue
1. Open any app with a text field.
2. Touch and hold the globe key on the current keyboard.
3. Choose **Monologue**.
4. Tap the microphone in the Monologue keyboard and speak.
The finished text appears in the active text field. You can change keyboard behavior under **Monologue → Settings → Keyboard**.
## Optional shortcuts
Monologue includes actions for Apple Shortcuts. On an iPhone with an Action Button, you can assign the **Dictation to Clipboard** shortcut to start and stop dictation without tapping the keyboard microphone. Follow [Action Button and Shortcuts](/iphone-and-ipad/action-button-and-shortcuts).
If the keyboard is missing or cannot record, see [iPhone and iPad troubleshooting](/troubleshooting/iphone-and-ipad).
---
# Set up Monologue on Mac
Source: https://www.monologue.to/docs/getting-started/mac
This guide takes about five minutes. You are ready when the Monologue icon appears and the shortcut starts a recording.
## Install and sign in
1. Download Monologue from [monologue.to](https://monologue.to).
2. Move the app to Applications and open it.
3. Sign in, then follow the setup guide in the app.
Use the same sign-in method on every device. If you chose **Sign in with Apple** and hid your email, choose the same option on your other devices.
## Grant permissions
Monologue asks for permissions as you set it up:
| Permission | Required? | Why Monologue uses it |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Microphone | Yes | Records your voice while you dictate. |
| Accessibility | Yes for automatic pasting | Inserts the finished text into the app you are using and listens for your chosen shortcut. |
| Screen Recording | Optional | Provides richer on-screen context when Deep Context is enabled. You can choose **Not now** and use dictation without it. |
If macOS does not show the prompt, open **System Settings → Privacy & Security**, choose the permission, and enable Monologue. Quit and reopen Monologue after changing Accessibility or Screen Recording access.
:::note[Screen Recording is optional]
Microphone and Accessibility are the core permissions for Mac dictation. Screen Recording is not required for ordinary dictation.
:::
## Choose a shortcut
The default push-to-talk shortcut is the right-side Option key. Hold it while speaking, then release it to finish.
For longer dictations, use a hands-free shortcut: tap it once to start, then tap it again to finish. Push-to-talk and hands-free bindings can be configured separately under **Monologue → Settings → Dictation**.
## Try it
1. Open a text field in Notes, Messages, Slack, or another app.
2. Hold the dictation shortcut.
3. Speak naturally.
4. Release the shortcut and wait for the text to appear.
If recording works but nothing is inserted, follow [Fix dictation and pasting](/troubleshooting/dictation-and-pasting).
---
# Where Monologue is available
Source: https://www.monologue.to/docs/getting-started/platform-availability
Monologue is available on:
- **Mac:** Dictate into other Mac apps, create Voice Notes, and manage your history and personalization.
- **iPhone:** Dictate with the Monologue keyboard, Apple Shortcuts, or the Action Button on supported devices.
- **iPad:** Dictate with the Monologue keyboard and use the Monologue app.
Monologue does not currently offer Windows or Android apps. This page describes current availability and does not promise release dates for other platforms.
Local transcription is available only on Apple silicon Macs. Remote transcription remains the recommended option for most people.
---
# Choose MCP, CLI, or the Notes API
Source: https://www.monologue.to/docs/integrations/choose-a-connection
Monologue offers several read-only ways to use Voice Notes outside the app. Choose based on where the work will happen.
| Use case | Choose |
| ------------------------------------------ | ---------------------------- |
| Chat or desktop app with hosted connectors | MCP |
| Terminal workflow or local coding agent | Monologue CLI or agent setup |
| Your own application or automation | Public Notes API |
| Event delivery to a server, when enabled | Webhooks |
All of these connections should receive only the access they need. The current public Notes access is read-only: it can list, search, and retrieve notes, but it cannot edit or delete them.
## MCP
Use [MCP](/integrations/mcp) when the AI app supports a hosted MCP connection. The browser authorization flow avoids copying an API key into the client and lets you revoke that connection later.
## CLI and local agents
Use the [Monologue CLI](/integrations/cli) for terminal searches, scripts, and local agents. It uses a personal Notes API key stored on your computer.
On Mac, **Settings → Notes → Connect an AI Agent** can copy a current setup message for supported local agents. The message includes installation, authentication, and a verification step.
## Public API and webhooks
Use the [Public Notes API](/public-api) when you are building your own integration. Create a separate key for each integration so you can revoke one without interrupting the others.
Webhooks deliver note-processing events to a server. They are not enabled for every account. If Webhooks appears in your settings, read the [webhook guide](/public-api/webhooks) before accepting events in production.
---
# Use the Monologue CLI
Source: https://www.monologue.to/docs/integrations/cli
The Monologue CLI provides read-only access to your Voice Notes. It can list notes, search them, and retrieve a note's summary or transcript.
## Install and authenticate
On Mac, open **Settings → Notes → Monologue CLI** and copy the current install command. It installs the CLI and starts onboarding.
During onboarding:
1. Create a Notes API key when prompted, or create one under **Settings → Notes → API keys**.
2. Copy the key when Monologue shows it. The complete secret is shown only once.
3. Paste it into `monologue onboarding`.
4. Let the CLI verify the connection.
Store the key only on a device and in tools you trust. Do not put it in source control, a shared shell history, or a prompt sent to an unrelated service.
## Find notes
Run `monologue --help` and `monologue notes --help` for the commands supported by your installed version. Common tasks include:
```bash
monologue notes list --limit 10
monologue notes list --q "customer interview"
monologue notes get NOTE_ID
monologue notes get NOTE_ID --field transcript
```
The CLI cannot create, edit, or delete notes.
## Connect a local agent
Open **Settings → Notes → Connect an AI Agent** on Mac and copy the generated setup message. Paste it into the local agent you want to configure. Use this generated message instead of an older command from a guide, because supported agents and installation steps can change.
## Revoke access
Revoke the CLI's API key in Monologue or under **Web app → Settings → API keys**. Commands using that key stop working immediately. Create a new key and run onboarding again if you want to reconnect.
If you used the same key in more than one tool, revoking it disconnects all of them. Separate keys make future rotation safer.
---
# Connect an AI agent to your notes
Source: https://www.monologue.to/docs/integrations/mcp
Monologue can connect supported AI agents to your Voice Notes through the Model Context Protocol (MCP). This lets the agent find and read notes you authorize without copying each transcript by hand.
The connection uses Monologue's hosted MCP service and an authorization screen in your browser. You do not need to create a separate API key. Note access is read-only: a connected agent can search and read available note content, but it cannot edit or delete your notes through MCP.
## Set up a connection
1. On Mac, open **Settings → Notes**.
2. Find **Connect an AI Agent**.
3. Choose your AI tool and use the current setup command shown by Monologue.
4. Approve the connection in your browser when prompted.
5. Return to the AI tool and ask it to list a recent note.
Use Monologue's in-app setup command rather than an older command copied from a guide—the available clients and authentication flow can change.
Some AI tools can connect to a remote MCP service directly. Others use a local compatibility helper. Follow the current option shown for your tool in Monologue instead of reusing another client's command.
## What an agent can read
A connected agent may receive note titles, summaries, timestamps, and transcripts for notes available to your Monologue account. Only connect an AI tool when you trust both the tool and the people who can access its conversations.
The agent still decides how to use the results it reads. Review its answer before sharing or acting on it.
## Disconnect
Remove the Monologue MCP connection from your AI tool. You can also revoke the connection from **Settings → Notes** in Monologue. Revoking access prevents that authorization from reading notes again.
If you reconnect later, use the current setup flow and approve a new authorization. Do not delete a shared MCP authentication folder or run a broad cleanup command: that can sign other services out as well.
## If the connection stops working
1. Confirm that the Monologue connection is still enabled in the AI tool.
2. Disconnect only the Monologue connection.
3. Revoke its authorization under **Settings → Notes**.
4. Run the current setup flow again and approve it in your browser.
If the tool opens a browser but does not return to the connection flow, retry once with your default browser and confirm that pop-ups or redirects were not blocked.
---
# Action Button and Shortcuts
Source: https://www.monologue.to/docs/iphone-and-ipad/action-button-and-shortcuts
Quick Dictation starts or stops from the Action Button or an Apple Shortcut without tapping the microphone in the Monologue keyboard first. The setup assigns Monologue's **Dictation to Clipboard** shortcut to the button.
## Before you start
- Finish [setting up the Monologue keyboard](/iphone-and-ipad/keyboard-and-full-access).
- Allow microphone access for Monologue.
- Allow Live Activities for Monologue in iOS Settings. The Action Button flow uses a Live Activity while recording.
## Set up the Action Button
On a supported iPhone:
1. Open **Monologue → Settings → Action Button**.
2. Follow the guided setup to add the **Dictation to Clipboard** shortcut.
3. Open **iOS Settings → Action Button**.
4. Choose **Shortcut**, then select **Dictation to Clipboard**.
## Dictate with the Action Button
1. Put the cursor where you want the result.
2. Press and hold the Action Button to start recording.
3. Press and hold it again when you finish.
Keep the Monologue keyboard selected when you want the result inserted at the cursor. The result is also available in [History](/dictation/history).
If the Action Button already runs another shortcut, changing it replaces that assignment.
## Use Monologue in Apple Shortcuts
1. Open the **Shortcuts** app.
2. Create or edit a shortcut.
3. Search the action list for **Monologue**.
4. Add a dictation action and choose Blazing Fast or one of your custom modes when the action offers that option.
You can then run the shortcut from the Shortcuts app, a widget, Siri, or another automation supported by iOS.
Monologue also provides a **Record Note** shortcut for starting a Voice Note instead of returning text to the shortcut.
Quick Dictation still needs microphone permission. It also does not use the **Pause Other Audio** preference, so music or a call may continue playing while it records.
---
# Set up the Monologue keyboard
Source: https://www.monologue.to/docs/iphone-and-ipad/keyboard-and-full-access
Monologue works as a custom keyboard, so you can dictate into the text field in front of you.
## Enable the keyboard
1. Open the Monologue app and finish setup.
2. Open **iOS Settings → General → Keyboard → Keyboards**.
3. Tap **Add New Keyboard**, then choose **Monologue**.
4. Tap **Monologue** in the keyboard list and turn on **Allow Full Access**.
Full Access is required for Monologue to process dictation from inside another app. iOS displays its standard third-party keyboard warning when you enable it.
## Dictate in another app
1. Tap a text field.
2. Touch and hold the globe key, then choose **Monologue**.
3. Tap the microphone and speak.
4. Stop the recording to insert the finished text.
Some secure fields, including password fields, switch back to an Apple keyboard. This is controlled by iOS.
## Change keyboard behavior
Open **Monologue → Settings → Keyboard** to control:
- Character previews, key sounds, and haptics.
- Auto-capitalization, autocorrect, suggestions, and on-device predictions.
- Caps Lock and the double-space period shortcut.
- The appearance of the Monologue key.
If the keyboard is missing or cannot record, see [iPhone and iPad troubleshooting](/troubleshooting/iphone-and-ipad).
---
# Preferences and dictation modes
Source: https://www.monologue.to/docs/iphone-and-ipad/preferences-and-modes
Open **Monologue → Settings → Preferences** to adjust dictation on your iPhone or iPad.
## Audio and recording preferences
You can choose:
- The language or languages you dictate in.
- How long Monologue waits before ending a quiet recording.
- Whether to prefer the device's built-in microphone.
- Whether other audio pauses while you dictate.
- Dictation sounds and haptic feedback.
:::info[Quick Dictation and other audio]
The **Pause Other Audio** preference does not apply when Quick Dictation starts from the Action Button or Apple Shortcuts.
:::
## Choose how Monologue writes
Open **Settings → Dictation Instructions** to select or edit a mode. A mode tells Monologue how to shape the finished text—for example, which instructions to follow for a particular kind of writing.
The Monologue keyboard and Apple Shortcuts can use your custom modes. You can also choose **Blazing Fast** when speed matters more than cleanup. Blazing Fast returns a more direct transcript and does not apply the usual writing instructions.
## Show progress outside the app
In Preferences, turn on Live Activities for **Keyboard Dictation** or **Voice Notes** to see recording progress on the Lock Screen and, on supported devices, in the Dynamic Island.
---
# Use Australian or British English spelling
Source: https://www.monologue.to/docs/personalize/australian-or-british-english
Monologue does not currently have separate Australian English or British English choices under Recording languages. Keep English selected for transcription, then use Dictation Instructions—Monologue's global custom instructions—to choose the regional spelling and writing conventions you prefer.
## Set your spelling preference
On Mac:
1. Select **Instructions** in the Monologue sidebar.
2. Find **Dictation instructions**.
3. Add a clear instruction such as:
```text
Use Australian English spelling and conventions. Prefer forms such as organise, colour, and centre.
```
On iPhone or iPad, open **Settings → Dictation Instructions** and add the same instruction.
For British English, replace "Australian English" with "British English." This instruction applies to your normal dictations; you do not need to change the spoken language away from English.
If a custom mode has **Override default** enabled and the spelling changes only in that mode, add the same regional preference to that mode's instructions.
## Use the dictionary for specific words
Dictation Instructions are best for an overall regional preference. Use the [dictionary](/personalize/dictionary) when a particular name, product, technical term, or spelling still needs correction.
Keep dictionary entries specific. Add the exact spelling you want, or add a replacement when the spoken and written forms differ. Do not add a paragraph of regional spelling rules to the dictionary.
## If spelling is still inconsistent
Submit **👎** on the exact affected dictation and include the spelling you expected. The attached example gives support the affected result needed to investigate the accuracy issue; a newly typed version does not contain the same evidence.
---
# Teach Monologue your words
Source: https://www.monologue.to/docs/personalize/dictionary
Use the dictionary for words that are important to you but uncommon in everyday speech: people, company names, product names, acronyms, and technical terms.
## Add a word
1. Open Monologue and select **Dictionary**.
2. Add the word exactly as you want it written.
3. Add a replacement when the spoken form and written form differ.
For example, you can map a commonly misheard pronunciation to the correct product name. Keep each entry focused; a short list of precise terms works better than paragraphs of instructions.
## Import an existing dictionary
If you already use another voice tool, Monologue can import dictionaries from Aqua Voice, Wispr Flow, Superwhisper, and Willow Voice. Open **Dictionary**, choose the import option, and follow the prompts for your source app.
## If a word is still wrong
- Confirm the entry uses the spelling and capitalization you want.
- Remove duplicate or conflicting entries.
- Speak the full phrase naturally instead of isolating the word.
- Submit the affected dictation with **👎** so support can inspect the exact example.
---
# Modes and custom instructions
Source: https://www.monologue.to/docs/personalize/modes-and-instructions
Modes tell Monologue how you want a dictation rewritten. Use them for recurring work such as messages, email, or structured updates.
## Choose a mode
Open **Customization** on Mac or **Modes** on iPhone and iPad. Select the mode that best matches the result you want before dictating. On Mac, you can also tap right Shift while dictating to open the mode picker.
Examples:
- A messaging mode can keep the result short and conversational.
- An email mode can turn fragments into a complete message.
- A project-update mode can apply a repeatable structure and terminology.
## Activate a mode for an app or website
On Mac, a mode can activate automatically for selected apps or websites. Add an app, or enter a website domain such as `chatgpt.com`. Monologue uses the matching mode when that app or site is active.
Turn on **Override default** when the mode should take precedence over the normal selection. Keep activation lists focused so two modes do not compete for the same place.
## Send automatically
Enable **Auto enter** when Monologue should simulate a send key after it finishes processing. Choose the key expected by the target app.
Use Auto enter only in apps where sending immediately is safe. Leave it off for email, forms, terminals, and anywhere you normally review text before submitting it.
## Blazing Fast
**Blazing Fast** favors speed over cleanup. It skips the normal smart post-processing path, so filler words, false starts, rough punctuation, and inconsistent casing may remain.
Blazing Fast can have its own app and website activations and Auto enter behavior. Use it when latency matters more than polished output; use Default or a custom mode when you want Monologue's normal cleanup.
## Write useful instructions
Describe the output, not every transformation the model should perform. For example:
```text
Write a concise project update. Keep product names exactly as dictated and use bullets only when I list three or more items.
```
Start with one clear instruction, test it in the app where you normally write, and add detail only when a recurring problem remains. Put names and terminology in the [dictionary](/personalize/dictionary) instead of repeating them in every mode.
For regional spelling preferences, see [Use Australian or British English spelling](/personalize/australian-or-british-english).
---
# Public API
Source: https://www.monologue.to/docs/public-api
The Public API lets a Monologue user build personal workflows around their Voice Notes. It is separate from the Enterprise API for approved integrations.
Use these guides to create a token, choose an integration approach, and handle webhooks. Use the endpoint reference when you need the exact request parameters and response schemas.
List notes, search transcripts and summaries, and download original recordings.
React when a note finishes processing or fails.
Check exact parameters, response fields, schemas, and generated examples.
## What you need
- A Monologue account with Voice Notes.
- A personal API token created in the Monologue app.
- An HTTPS endpoint if you want to receive webhooks.
The current token scope is `notes:read`. The API cannot create, edit, or delete notes.
Start with the [quickstart](/public-api/quickstart). Keep the [endpoint reference](/public-api/reference) nearby while you implement requests.
---
# Public API authentication
Source: https://www.monologue.to/docs/public-api/authentication
Public API requests use a personal token in the Bearer authorization header:
```http
Authorization: Bearer mono_pat_...
```
Personal tokens belong to one Monologue user. The supported scope is currently `notes:read`, which allows reading owned notes and downloading their original recordings. Existing tokens with this scope work for recording access; you do not need to create a new key.
## Create a token
Open **Settings → Notes → API Keys** in the Monologue Mac app. Choose a name that identifies the integration, create the token, and copy the secret immediately. You will not be able to reveal the same secret later.
You can optionally set an expiration date. Prefer a short useful lifetime for scripts or temporary integrations.
## Store it safely
- Put the token in a server-side environment variable or secret manager.
- Never embed it in a website, browser extension, distributed app, or client-side bundle.
- Use a separate token for each integration so you can revoke one without affecting the others.
- Do not include the token in URLs, logs, analytics events, or support requests.
## Revoke a token
Return to **Settings → Notes → API Keys** and revoke the key. Requests using it will begin returning `401`. If a token may have leaked, revoke it immediately and create a replacement.
Revoking a token prevents it from requesting new recording URLs. Previously issued signed recording URLs can remain usable until their one-hour expiry. Keep these URLs private and do not forward your API token when downloading from them.
---
# Errors and pagination
Source: https://www.monologue.to/docs/public-api/errors-and-pagination
## Pagination
The Notes list endpoint uses cursor pagination. Treat `next_cursor` as an opaque value: do not parse it or construct one yourself.
1. Request the first page without a cursor.
2. Process `items`.
3. If `next_cursor` is not `null`, pass it as the next request's `cursor`.
4. Stop when `next_cursor` is `null`.
Keep the same filters while walking a result set. A cursor is tied to the ordering and filters used to create it.
## Errors
| Status | Meaning | What to do |
| ------ | --------------------------------------------------------- | ------------------------------------------------ |
| `400` | A query value or cursor is invalid. | Correct the request; do not retry unchanged. |
| `401` | The token is missing, invalid, expired, or revoked. | Supply a valid Bearer token. |
| `403` | The token is missing `notes:read`. | Create or use a token with the required scope. |
| `404` | The note does not exist or is not available to this user. | Verify the note ID and account. |
| `422` | One or more parameters failed validation. | Inspect the response and correct the parameters. |
| `5xx` | Monologue could not complete the request. | Retry with exponential backoff and jitter. |
Do not automatically retry `4xx` responses without changing the request. For transient network failures and `5xx` responses, use bounded exponential backoff and preserve the original request filters.
---
# Read Voice Notes
Source: https://www.monologue.to/docs/public-api/notes
All Notes endpoints use the base URL:
```text
https://api.monologue.to/v1/public-api
```
## List notes
```http
GET /notes
```
The list response contains note metadata, summaries, and tags. Use the detail endpoint when you need the transcript or original recording. List responses do not include recording URLs.
| Query parameter | Meaning |
| ---------------- | --------------------------------------------------------------------- |
| `limit` | Items per page. Defaults to 20; maximum 100. |
| `cursor` | Opaque `next_cursor` from the previous response. |
| `created_after` | Notes created after this ISO 8601 timestamp. |
| `created_before` | Notes created before this ISO 8601 timestamp. |
| `updated_after` | Notes updated after this ISO 8601 timestamp. |
| `q` | Searches title, summary, and transcript. |
| `tag_id` | Matches any supplied tag. Repeat the parameter for more than one tag. |
```bash
curl --get "https://api.monologue.to/v1/public-api/notes" \
--header "Authorization: Bearer $MONOLOGUE_API_TOKEN" \
--data-urlencode "q=launch review" \
--data-urlencode "created_after=2026-07-01T00:00:00Z" \
--data-urlencode "limit=20"
```
## Retrieve a note
```http
GET /notes/{note_id}
```
The detail response includes `transcript`, `transcript_segments`, and recording details in addition to the fields returned by the list endpoint.
```bash
curl "https://api.monologue.to/v1/public-api/notes/$NOTE_ID" \
--header "Authorization: Bearer $MONOLOGUE_API_TOKEN"
```
Only notes owned by the authenticated user are available. An unknown or inaccessible note returns `404`.
## Download the original recording
The single-note response includes these fields:
| Field | Meaning |
| -------------------------- | ------------------------------------------------------------------------ |
| `recording_url` | Signed download URL for the original uploaded audio, valid for one hour. |
| `recording_url_expires_at` | UTC expiration timestamp for the URL. |
| `recording_content_type` | Recorded MIME type, or `null` when unavailable. |
| `recording_bytes` | Recorded file size in bytes, or `null` when unavailable. |
Download the returned `recording_url` directly. Do not send your Monologue API token to the storage URL. This example uses `jq` to read the JSON response:
```bash
NOTE_JSON=$(curl --fail --silent --show-error \
"https://api.monologue.to/v1/public-api/notes/$NOTE_ID" \
--header "Authorization: Bearer $MONOLOGUE_API_TOKEN")
RECORDING_URL=$(printf '%s' "$NOTE_JSON" | jq --raw-output '.recording_url')
curl --fail --show-error "$RECORDING_URL" --output recording.m4a
```
Choose a filename extension that matches `recording_content_type` when available. Monologue returns the uploaded file in its existing format; it does not convert or enhance the audio for download. Recording access is available independently of transcription status, so a failed transcription does not prevent downloading an existing recording.
## Refresh a recording URL
```http
GET /notes/{note_id}/audio-url
```
Use the same personal API token with `notes:read` to request a fresh link without fetching the full note:
```bash
curl --fail "https://api.monologue.to/v1/public-api/notes/$NOTE_ID/audio-url" \
--header "Authorization: Bearer $MONOLOGUE_API_TOKEN"
```
```json
{
"audio_url": "https://storage.example/recording.m4a?signature=example",
"expires_in": 3600
}
```
`audio_url` points to the same recording as the detail response's `recording_url`. `expires_in` is the URL lifetime in seconds. Fetching the full note again also produces a fresh link.
Treat signed URLs as secrets. Anyone holding a URL can download the recording until it expires, even after the API token that requested it is revoked. Save the note ID for future requests instead of treating the URL as a permanent link.
A signed URL does not verify that the stored file still exists. If a download fails because the URL expired, request a fresh link and retry. If the recording has been removed, refreshing the URL cannot restore it; the note's text can still be retrieved.
---
# Public API quickstart
Source: https://www.monologue.to/docs/public-api/quickstart
## 1. Create a personal API token
On Mac, open **Settings → Notes → API Keys**. Create a key with the `notes:read` scope and copy the token when it appears. The full secret is shown only once.
```bash
export MONOLOGUE_API_TOKEN="mono_pat_..."
```
Treat this token like a password. Do not put it in browser code, mobile apps, source control, screenshots, or support messages.
## 2. List your notes
```bash
curl --request GET \
--url "https://api.monologue.to/v1/public-api/notes?limit=10" \
--header "Authorization: Bearer $MONOLOGUE_API_TOKEN"
```
The response returns note summaries and an opaque cursor for the next page:
```json
{
"items": [
{
"note_id": "0198b68f-c6e1-7891-a341-803eb8fe421f",
"title": "Launch review",
"summary": "The team reviewed the launch plan.",
"tags": [],
"created_at": "2026-07-20T10:30:00Z",
"updated_at": "2026-07-20T10:35:00Z"
}
],
"next_cursor": null
}
```
## 3. Retrieve the full note
```bash
curl --request GET \
--url "https://api.monologue.to/v1/public-api/notes/0198b68f-c6e1-7891-a341-803eb8fe421f" \
--header "Authorization: Bearer $MONOLOGUE_API_TOKEN"
```
The detail response also includes the transcript, transcript segments, and a one-hour `recording_url` for the original uploaded audio. Download that URL without sending your API token. To refresh an expired link, request `GET /v1/public-api/notes/{note_id}/audio-url` with your token; it returns `audio_url` and `expires_in` in seconds.
Continue with [filtering, pagination, and recording downloads](/public-api/notes) or [webhooks](/public-api/webhooks).
---
# Monologue Public API
Source: https://www.monologue.to/docs/public-api/reference
Read your notes with a personal API token, and receive webhook events when notes finish processing. All API endpoints in this reference require the `notes:read` scope; the Webhooks section documents the events Monologue delivers to your endpoint and how to verify them.
To download an original recording, list your notes, then fetch `GET /v1/public-api/notes/{note_id}` and download its `recording_url`. List responses do not include recording links. The URL expires after one hour; fetch the note again or call `GET /v1/public-api/notes/{note_id}/audio-url` for a fresh `audio_url` and `expires_in` (seconds). Download the returned URL without forwarding your API token to storage.
```bash
curl -H "Authorization: Bearer $MONOLOGUE_API_TOKEN" \
"https://api.monologue.to/v1/public-api/notes/$NOTE_ID/audio-url"
# Download the audio_url from the JSON response:
curl --fail --output recording.m4a "$AUDIO_URL"
```
Recordings retain their uploaded format; choose an output extension appropriate to the note's `recording_content_type` when available. Signed URLs grant access to anyone holding them until expiry, even if the API token is revoked. A signed URL does not verify file availability; a removed recording can fail to download while the note's text remains accessible.
## Notes
Read the authenticated user's notes with a personal API token.
---
# Get a note
Source: https://www.monologue.to/docs/public-api/reference/notes/getnote
Returns the full details for a single note that belongs to the authenticated user, including a one-hour download URL for the original uploaded recording. Requires `notes:read`. Refresh an expired URL by fetching this note again or calling GET /v1/public-api/notes/{note_id}/audio-url. Recording access does not depend on transcription status.
---
# Refresh a note recording URL
Source: https://www.monologue.to/docs/public-api/reference/notes/getnoteaudiourl
Returns a fresh one-hour download URL for an owned note's original uploaded recording. Requires a personal API token with `notes:read`. The `audio_url` points to the same recording as `recording_url` in the single-note response; `expires_in` is the URL lifetime in seconds. Download directly from the returned URL without sending your API token. Treat signed URLs as secrets: anyone with the URL can download the recording until it expires, including after the API token is revoked. A signed URL does not guarantee that the stored file still exists.
---
# List notes
Source: https://www.monologue.to/docs/public-api/reference/notes/listnotes
Returns the authenticated user's notes. Authenticate with a personal API token that includes the `notes:read` scope.
---
# Webhooks
Source: https://www.monologue.to/docs/public-api/webhooks
Webhooks let your server react to a note without polling. Create and manage endpoints from **Settings → Notes → Webhooks** when that option is available for your account.
| Event | When it is sent |
| ---------------- | --------------------------------------------------------------------------------------- |
| `note.processed` | A note finished processing. The payload includes its transcript, summary, and metadata. |
| `note.failed` | A note could not be processed. The payload includes the error message. |
| `ping` | A one-time connectivity check when you create an endpoint. |
Endpoint URLs must be public `https://` URLs. Monologue rejects plain HTTP, localhost, and private network addresses.
## Optional Bearer authentication
If your receiver requires a Bearer token, choose **Bearer token** when creating the endpoint and paste the raw token only. Monologue adds the `Bearer` prefix and sends `Authorization: Bearer ` with the creation ping, test events, automatic deliveries, retries, and manual redeliveries.
The saved token is encrypted and is never displayed again. Use the endpoint menu to replace or remove it. Bearer authentication controls access to your receiver; Standard Webhooks signatures still prove that the request came from Monologue. Both work together, so continue verifying every signature below.
## Verify every signature
Each request includes `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers and is signed according to the [Standard Webhooks](https://www.standardwebhooks.com/) specification. Verify the raw request body with your endpoint's `whsec_...` secret before parsing or processing it.
```python
from fastapi import FastAPI, Request, Response
from standardwebhooks import Webhook, WebhookVerificationError
app = FastAPI()
wh = Webhook("whsec_...")
@app.post("/webhooks/monologue")
async def monologue_webhook(request: Request) -> Response:
body = await request.body()
try:
event = wh.verify(body, dict(request.headers))
except WebhookVerificationError:
return Response(status_code=401)
# Enqueue event for asynchronous processing here.
return Response(status_code=204)
```
```typescript
import express from "express";
import { Webhook } from "standardwebhooks";
const app = express();
const wh = new Webhook(process.env.MONOLOGUE_WEBHOOK_SECRET!);
app.post("/webhooks/monologue", express.raw({ type: "application/json" }), (req, res) => {
try {
const event = wh.verify(req.body, req.headers as Record);
res.status(204).end();
// Enqueue event for asynchronous processing here.
} catch {
res.status(401).end();
}
});
```
Do not parse and re-serialize JSON before verification. The signature covers the exact request bytes.
## Delivery behavior
- Delivery is at least once. Deduplicate using `webhook-id`, which remains stable across retries.
- Events are not guaranteed to arrive in order. Use the Notes API as the source of truth.
- Return a `2xx` within 20 seconds and process heavy work asynchronously.
- Automatic events retry up to eight attempts over about 28 hours after a timeout or non-2xx response.
- Redirects are not followed; a `3xx` counts as a failed attempt.
- A `410 Gone` response disables the endpoint immediately.
- Continued failures trigger a warning after 24 hours and disable the endpoint after 72 hours. Events sent while disabled are not replayed.
## Rotate the secret
Rotate an endpoint's secret from Settings. The previous secret remains valid for 24 hours, and deliveries contain signatures for both active secrets during the overlap. The Standard Webhooks library accepts a match from either secret.
For local testing, expose your server through an HTTPS tunnel and use **Send test event** from the endpoint settings. Manual tests and redeliveries are attempted once rather than retried automatically.
---
# Contact support
Source: https://www.monologue.to/docs/support/contact-support
Email [support@monologue.to](mailto:support@monologue.to) when the guides here do not resolve the problem.
Include:
- The email address on your Monologue account.
- Your device, operating system, and Monologue version.
- Whether the problem is in Dictation or Voice Notes.
- The app you were using and the approximate time it happened.
- What you expected and what happened instead.
For a dictation-quality issue, submit **👎** on the exact affected dictation. For a Voice Note issue, use **Report** from that note. Then mention in your email that you submitted the example.
Do not email passwords, authentication codes, API keys, or other secrets.
---
# Connection checks and support diagnostics
Source: https://www.monologue.to/docs/troubleshooting/connection-and-diagnostics
## Run the connection check
On Mac, open **Settings → Help & support → Check connection**. On iPhone or iPad, open **Settings → Help Center → Check connection**.
The check sends a small test upload to Monologue and reports latency and upload performance. It does not use one of your recordings. Run it on the same network where the problem occurs.
If the check fails or reports an unstable connection:
1. Confirm other websites load on the device.
2. Turn off a VPN, proxy, firewall rule, or network filter temporarily, if your organization permits it, then test again.
3. Try a different network, such as a phone hotspot.
4. Return to the original network and run one short dictation.
A successful check does not rule out a brief interruption. Note whether the problem affects remote dictation, smart formatting, Voice Notes, sign-in, or billing, because those requests can fail independently.
## Send useful evidence
When you [contact support](/support/contact-support), include:
- The Monologue account email.
- Device model, operating-system version, and Monologue app version.
- Approximate time and timezone of the problem.
- The affected app, language, mode, microphone, and network type when relevant.
- The connection-check result and whether another network worked.
- Exact steps to reproduce the issue and any error text shown.
For a Mac app problem, open **Settings → Help & support → Share logs** when support asks for logs. For a dictation-quality problem, submit **👎** on the affected dictation. For a Voice Note problem, use **Report** inside that note.
Do not send passwords, authentication codes, API keys, full payment-card numbers, or unrelated private documents.
---
# Dictation or pasting is not working
Source: https://www.monologue.to/docs/troubleshooting/dictation-and-pasting
## No recording starts
1. Open **Settings → Mic & Audio** and confirm the correct microphone is selected.
2. Open **System Settings → Privacy & Security → Microphone** and enable Monologue.
3. Test the microphone in another recording app.
4. Return to Monologue and try a short dictation.
If the shortcut does nothing, open **System Settings → Privacy & Security → Accessibility**, remove and re-enable Monologue, then relaunch it. Also open **Settings → Dictation** and confirm the active shortcut.
## The shortcut conflicts with another action
Monologue warns when a shortcut is already used by another Monologue action. Choose a different shortcut in **Settings → Dictation**.
If there is no warning but another app responds first, temporarily disable that app's global shortcut and test again. Avoid common macOS shortcuts and assign each Monologue action a unique combination.
## The transcript does not appear in the current app
Confirm Accessibility access is enabled and that the text field still has focus when the dictation finishes. Turn on **Settings → Dictation → Leave transcript on clipboard**; if automatic insertion fails, you can paste the result manually.
Some secure fields and apps restrict programmatic pasting. Test in TextEdit or Notes to determine whether the issue is specific to one app.
## Monologue says “Copied” or the app changed
Monologue avoids pasting into the wrong place. If the active app or text target changes before processing finishes, or if the current field cannot accept automated text, Monologue leaves the transcript on your clipboard and shows **Copied**.
Return to the intended field and press **Command-V**. For a repeated problem:
1. Start and finish a short dictation without switching apps.
2. Keep the same editable text field focused until the transcript appears.
3. Test in TextEdit. If TextEdit works, the original app or field is restricting insertion.
4. Confirm Monologue still has Accessibility access.
For incorrect text rather than insertion trouble, see [Wrong language or unexpected words](/troubleshooting/language-and-unexpected-words).
---
# iPhone and iPad keyboard problems
Source: https://www.monologue.to/docs/troubleshooting/iphone-and-ipad
## The keyboard is missing
Open **Settings → General → Keyboard → Keyboards → Add New Keyboard**, add Monologue, then switch keyboards with the globe key in a text field.
## Dictation does not start or return text
1. In **Settings → General → Keyboard → Keyboards**, tap Monologue and enable **Allow Full Access**.
2. Open the Monologue app once and confirm you are signed in.
3. Check microphone access in **Settings → Privacy & Security → Microphone**.
4. Return to the app where you want to type, select Monologue, and try a short dictation.
Apple does not give third-party keyboards full access in some secure fields. If Monologue disappears on a password or payment field, switch back in a normal text field.
## Why Start Monologue opens the app
The keyboard uses a microphone session owned by the main Monologue app. When the session is not active, tapping **Start Monologue** may open the app so iOS can activate the microphone. Monologue then tries to return to the app where you were typing. If it cannot return automatically, swipe back to that app.
While the session is active, iOS shows its microphone indicator and Monologue can show a Live Activity on the Lock Screen or Dynamic Island. You can control the session timeout and Live Activities under **Monologue → Settings → Preferences**.
If the keyboard returns to **Start Monologue**, activate the session again. A configured timeout, force-quitting Monologue, a call, an audio interruption, or an audio-route change can end or interrupt the session. Reopen Monologue after a force-quit before trying the keyboard again.
If recording starts but the level stays flat, open **Settings → Preferences** and test **Built-in Microphone**, especially when Bluetooth headphones are connected.
## The Action Button opens Monologue instead of recording
Open Monologue's **Action Button** settings and complete the setup shown there. Then review the Action Button assignment in iOS Settings and test it while the phone is unlocked.
---
# Wrong language or unexpected words
Source: https://www.monologue.to/docs/troubleshooting/language-and-unexpected-words
## Check recording languages
On Mac, open **Settings → Dictation → Recording languages**. On iPhone or iPad, open **Settings → Preferences → Languages**.
- Select the languages you actually speak during dictation.
- Leave the selection empty to use auto-detect.
- If auto-detect chooses the wrong language, select the intended language explicitly and try again.
- When using a local model on Mac, make your primary spoken language the selected language.
Test with a clear, complete sentence. Very short recordings, background speech, and abrupt language changes give detection less information.
Recording languages control the language you speak, not whether English uses Australian, British, or American spelling. For that preference, see [Use Australian or British English spelling](/personalize/australian-or-british-english).
## Fix names and specialized terms
Add names, product terms, abbreviations, and other unusual words to your [dictionary](/personalize/dictionary). Enter the spelling you want Monologue to produce, then try a new dictation.
If the raw words are close but the style is wrong, review the active [mode or dictation instruction](/personalize/modes-and-instructions). Test once with no mode selected to separate a transcription problem from an instruction or formatting problem.
## Report a result that is still wrong
Submit **👎** on the exact affected dictation. Include the intended language and what you expected in the feedback. Do not replace the example with a newly typed transcript; the affected dictation is the useful evidence.
Avoid including passwords, authentication codes, API keys, or other secrets in the report.
---
# Monologue is slow, stuck, or closes unexpectedly
Source: https://www.monologue.to/docs/troubleshooting/performance-and-crashes
## Recover first
1. Finish or save any active Voice Note if the app still responds.
2. Quit and reopen Monologue. On iPhone or iPad, reopen the main app before using the keyboard again.
3. Install the latest available Monologue version and operating-system update.
4. Restart the device if the problem returns immediately.
5. Reproduce the issue once with a short dictation in TextEdit on Mac or Notes on iPhone and iPad.
If only one app, microphone, mode, or language triggers the problem, include that detail in your report. Do not repeatedly reproduce a crash if it risks an unsaved Voice Note.
## Check updates, the network, and logs
On Mac, open **Settings → Help & support**. On iPhone or iPad, open **Settings → Help Center**. Check for an update and run the connection check. On Mac, you can also select **Share logs** if support asks for them.
For a dictation-quality problem, use **👎** on the exact dictation. For a Voice Note problem, use **Report** inside the affected note. These actions attach the affected item to the report.
When you [contact support](/support/contact-support), include the device, app version, operating-system version, approximate time and timezone, what you were doing, and whether the problem happens again after reopening the app.
---
# Automatic note tagging
Source: https://www.monologue.to/docs/voice-notes/automatic-note-tagging
Monologue can automatically organize new Voice Notes using tags you have already created.
## Set up automatic tagging
1. Open **Notes** in Monologue.
2. Create tags for the categories you want to use, such as **Meeting**, **Idea**, or **Personal**.
3. Record a new note.
After the note is processed, Monologue compares its title and summary with your existing tags. It may apply one tag when there is a strong match. If none of your tags fits, the note remains untagged.
Automatic tagging never creates a new tag. Create the tags you want Monologue to choose from before recording a note.
## Change an automatic tag
You can add, remove, or replace tags on a note at any time. You can also rename or delete tags from your tag list. Your manual changes are kept.
## Custom instructions and tags
Modes and custom instructions control how **Dictation** handles formatting, spelling, and tone. They do not control which tag is applied to a Voice Note.
For context used in future note summaries, use **About Me** in Notes settings. About Me can improve a summary, but automatic tagging still chooses only from the tags you have already created.
---
# Organize, edit, and share notes
Source: https://www.monologue.to/docs/voice-notes/organize-edit-and-share
Open **Notes** in a Monologue app or on the web to return to completed recordings.
## Find and organize notes
Search for a note by its title or content. Add tags for projects, people, or recurring topics, then use those tags to filter the Notes list. Monologue can also [automatically choose an existing tag](/voice-notes/automatic-note-tagging) for a new note.
## Refine a completed note
Depending on the device, you can:
- Edit the note title and summary.
- Read the transcript while listening to the original recording.
- Name detected speakers and mark one speaker as you.
- Regenerate the summary after correcting speaker names.
Regenerating a summary replaces the existing summary, including manual edits. Copy anything you want to keep first.
## Personalize future summaries
Use **About Me** in Notes settings to add relevant context such as your name, role, projects, and preferred terminology. Monologue uses it for new note summaries, not to rewrite completed notes automatically.
About Me accepts up to 10,000 characters. Keep it focused and do not add passwords or private keys.
## Copy or share
Available actions vary by device, but can include copying or sharing the summary, transcript, recording, or a public link.
Treat a note link as accessible to anyone who receives it. To withdraw access, open the note and choose **Stop Sharing**. The old link will no longer open the shared note.
Deleting a note is permanent. Stop sharing first if you only want to disable its public link while keeping the note in your account.
---
# Processing and recovery
Source: https://www.monologue.to/docs/voice-notes/processing-and-recovery
After you stop recording, Monologue uploads the audio and turns it into a transcript, summary, and speaker-separated conversation when the recording supports them.
## Understand the status
- **Uploading** means the recording is still moving from the device to Monologue.
- **Processing** means the upload finished and the note is being prepared.
- **Completed** means the available transcript, summary, speakers, and audio are ready.
- An error or retry action means the note needs attention before processing can finish.
Long recordings can take longer to upload and process. Keep the recording device online, and do not delete the note or its local recording while an upload is pending.
## Recover an interrupted recording
Monologue keeps recoverable recording state when possible. If the app or device stops unexpectedly, reopen Monologue and follow the recovery prompt before starting another long recording.
After recovery, confirm that the duration looks right and allow the upload to finish. A recovered note may still need to process before its summary and transcript appear.
## Retry or report a problem
If a note remains stuck:
1. Confirm the recording device is online.
2. Open the affected note and use the available retry action.
3. If it still fails, report the problem from that note so the correct example is attached.
You can also [contact support](/support/contact-support) with the recording time, device, and current status. Do not send private recording content unless support asks for it and you are comfortable sharing it.
---
# Record a Voice Note
Source: https://www.monologue.to/docs/voice-notes/record-a-note
Voice Notes are for recordings you want to keep, revisit, and organize. Use regular dictation when you only want text inserted into the app in front of you.
## Record on iPhone or iPad
1. Open **Notes** in Monologue.
2. Start a recording.
3. Pause and resume when needed.
4. Stop the recording when you are finished.
Monologue saves the recording and begins uploading it for processing. Keep the device online until the upload finishes.
## Record on Mac
Open **Notes** in Monologue or use your Voice Note shortcut. Before starting, choose the audio you need:
- **Microphone** records you and sound near your selected input.
- **System audio** adds sound playing through the Mac, such as the other side of a meeting.
System audio is optional and requires Screen Recording permission in macOS. If permission is missing, Monologue can continue with microphone audio only. Check the selected sources before an important recording.
## Use meeting detection on Mac
Meeting detection can remind you to start a Voice Note when a supported calling app begins using the microphone. You can turn it off entirely or suppress reminders for selected apps in **Settings → Notes**.
:::info[Record with permission]
Make sure everyone involved knows that the conversation is being recorded and follow the laws and policies that apply to you.
:::
---
# Edit, organize, and share notes
Source: https://www.monologue.to/docs/web-app/edit-organize-and-share
Open a completed note to make changes. The web app saves title and summary edits automatically after a short pause.
## Organize notes with tags
Add or remove tags from the note header. You can use the same tags as filters on the Notes page, which makes it easier to return to related meetings, interviews, or ideas.
## Identify speakers
Select a speaker in the transcript to give them a name or mark them as you. Only one speaker can be marked as you in a note.
After naming speakers, choose **Update summary with names** to generate a new summary with those names.
:::warning[Summary edits are replaced]
Regenerating replaces the current summary, including manual edits. Copy anything you want to keep before continuing.
:::
## Copy or share a note
From the note menu, you can:
- Copy the summary as plain text or Markdown.
- Copy the speaker-labeled transcript.
- Create or copy a share link after processing finishes.
- Permanently delete the note.
Anyone with a share link can open the shared note, so share it carefully. To disable an existing link in the web app, open **Share** and choose **Turn off** next to **Anyone with the link**. In a Monologue native app, choose **Stop Sharing**.
## Save a note someone shared with you
When you open a Monologue share link, you can read the note's summary and full transcript without creating an account. Choose **Save to Monologue** to keep the note in your own account. If you are not signed in, Monologue asks you to sign in or create an account and then returns you to the same note so you can finish saving it.
Saved notes appear under **Shared with me** in the web, Mac, and iOS apps. They are also available to tools you connect through Monologue MCP, alongside your own notes.
Saving gives you ongoing, read-only access; it does not copy the note or transfer ownership. The person who created the note still controls the original and can stop sharing it at any time.
---
# Use Notes on the web
Source: https://www.monologue.to/docs/web-app/notes
The Monologue web app gives you a larger workspace for reviewing and managing Voice Notes.
:::info[Record in a Monologue app]
The web app does not record new Voice Notes. Record on a supported Monologue app, then return to the web after the note syncs.
:::
## Find a note
Open **Notes** in the web app. You can:
- Search by title or note content.
- Filter by one or more tags.
- Move through older results with pagination.
- See whether a note is uploading, processing, completed, or needs attention.
Open a note to view its summary, speaker-separated transcript, recording, tags, duration, and recording date. Audio appears when the original recording is available.
If a recent note is missing, keep the recording device online until its upload finishes, then refresh the page.
---
# Web settings and connections
Source: https://www.monologue.to/docs/web-app/settings-and-connections
Open **Settings** in the web app to review your account and the services that can access it.
## Personalize new note summaries
Under **Settings → Notes**, add relevant background to **About Me**—for example, your role, recurring projects, preferred terminology, or important names. Monologue uses this context when it summarizes new notes.
About Me accepts up to 10,000 characters. Avoid adding passwords, private keys, or unrelated sensitive information.
## Manage API keys
Under **Settings → API Keys**, you can create, review, and revoke personal API keys.
Copy a new key when Monologue shows it. The complete secret is shown only once. Store it in a password manager or secret store, and revoke it if it is exposed or no longer needed.
## Review connected apps
Under **Settings → Connected apps**, review apps you have authorized with Monologue, including compatible MCP clients. Each connection shows its granted scopes, such as permission to read Notes or remain signed in.
Revoking a connection removes its access immediately. If you revoke the connection that powers your current web session, Monologue signs you out of the web app.
:::info[Availability]
Connected-app management and webhooks depend on account and backend availability. If a section says it is unavailable, it has not been enabled for that account yet.
:::
When webhooks are available, **Settings → Webhooks** lets you create an endpoint, inspect deliveries, send a test, pause or resume delivery, rotate the signing secret, and delete the endpoint. See the [webhook API guide](/public-api/webhooks) before using webhook data in production.